Microsoft’ 


Windows 


Programmer’s Reference 


Microsoft’ . 


Windows 


Programmer’s Reference 


New for Version 3 


Written, edited, and produced by 
Microsoft Corporation 


Distributed by Microsoft Press 


MICROSOFT. 
WINDOWS.. 


Information in this document is subject to change without notice and does not represent a commitment on 
the part of Microsoft Corporation. The software and/or databases described in this document are furnished 
under a license agreement or nondisclosure agreement. The software and/or databases may be used or 
copied only in accordance with the terms of the agreement. It is against the law to copy the software on 
any medium except as specifically allowed in the license or nondisclosure agreement. No part of this 
manual and/or databases may be reproduced or transmitted in any form or by any means, electronic or 
mechanical, including photocopying, recording, or information storage and retrieval systems. for any 
purpose other than the purchaser's personal use without the express written permission of Microsoft 
Corporation. 


PUBLISHED BY 

Microsoft Press 

A Division of Microsoft Corporation 

One Microsoft Way, Redmond, Washington 98052-6399 


©1990 Microsoft Corporation. All rights reserved. 
Printed and bound in the United States of America. 


Lucida Typeface Software. © 1985-1988 and 1990 by Bigelow & Holmes. 
U.S. Patent Nos. D289420, D289421, D289422, D289773 


Library of Congress Cataloging-in-Publications Data 


Microsoft Windows programmer’s reference / Microsoft Corporation. 
p. cm. -- (Microsoft Windows programmer’s reference library) 
Includes index. 
ISBN 1-55615-309-0 
1. Microsoft Windows (Computer programs) I. Microsoft. 
II. Series. 
QA76.76.W56M533 1990 
005.4'3--dc20 . 90-6037 
CIP 
6789 FGFG 4321 


Distributed to the book trade in Canada by Macmillan of Canada, a division of Canada Publishing 
Corporation. 

Distributed to the book trade outside the United States and Canada by Penguin Books Ltd. 
Penguin Books Ltd., Harmondsworth, Middlesex, England 

Penguin Books Australia Ltd., Ringwood, Victoria, Australia 

Penguin Books N.Z. Ltd., 182-190 Wairau Road, Auckland 10, New Zealand 


Microsoft, the Microsoft logo, MS, MS-DOS, Multiplan, PowerPoint. CodeView, GW-BASIC, QuickC, 
and XENIX are registered trademarks and /nformation at your fingertips, Making it all make sense, the 
Microsoft Mouse design, Toolbar, Windows, Windows/286, Windows/386, and Press are trademarks of 
Microsoft Corporation. 


U.S. Patent No. D302426 


Arial, Monotype, and Times New Roman are registered trademarks of The Monotype Corporation, PLC. 


AT and IBM are registered trademarks and PC/XT is a trademark of International Business Machines 
Corporation. 


AT&T is a registered trademark of American Telephone and Telegraph Company. 

Epson is a registered trademark of Epson America, Inc. 

Hewlett-Packard, HP Laserjet, and PCL are registered trademarks of Hewlett-Packard Company. 
Intel is a registered trademark and 386 is a trademark of Intel Corporation. 

Lotus, Signal, and 1-2-3 are registered trademarks of Lotus Development Corporation. 

Lucida is a registered trademark of Bigelow & Holmes. 

Nokia is a trademark of Nokia Corporation. 

Olivetti is a registered trademark of Ing. C. Olivetti. 

Paintbrush is a trademark of ZSoft Corporation. 

PostScript is a registered trademark of Adobe Systems, Inc. 


Document No. SY0302a-300-R00-1089 


Fo 


reword 


The Microsoft Windows Programmer’ s Reference Library is the core documenta- 
tion for Windows programmers that Microsoft provides with the Microsoft® 
Windows™ Software Development Kit (SDK). The information in these books is 
the most accurate and up-to-date information on Windows programming avail- 
able anywhere. The information represents everything Microsoft knows about 
programming Windows version 3.0 with Microsoft C (the recommended 
Windows programming language) and the tools we provide in the SDK. 


Certain example programs and tools referred to in this book are available only. 
in the Microsoft Windows SDK or Microsoft C 6.0 Professional Development 
System. However, if you are not currently programming for Windows, these 
volumes will still provide an excellent overview of the services that Microsoft 
Windows and the SDK provide to programmers—Microsoft Windows: A Guide 
to Programming and Microsoft Windows Programming Tools in particular—and 
an introduction to graphical user interface (GUI) programming. It is our hope 
that once you have “kicked the tires” of the Windows SDK by reading these 
books, you’ll be thoroughly convinced—and already prepared—to begin 
Windows programming the Microsoft way. 


Then as you continue to explore the Windows programming environment, 
Microsoft Windows Programmer’ s Reference will answer many of your program- 
ming questions. The book provides information on each Windows application 
programming interface (API) and describes its calls and services. For many 
Windows programmers, this book is the most frequently “thumbed,” dog-eared, 
and marked-up volume in the set. 


The Microsoft Windows Software Development Kit is available from your 
Microsoft product dealer. For further information on the Windows SDK or to 
obtain the name of your nearest Microsoft dealer, call the Microsoft Information 
Center at 1-800-426-9400. 


The Windows Software Development Kit 


The Windows high-level application programming interface consists of the 
functions, messages, data structures, data types, and files you need to develop 
applications that unleash the full capabilities of personal computers using Intel® 
286 and 386™ processors. The API’s device independence ensures compatibility 
with a broad array of displays, printers, and other devices, allowing you to con- 
centrate on your applications and their features and implementation. Develop- 
ment tasks are handled automatically, and advanced tools enable you to design 
icons, dialog boxes, fonts, menus, and other interface elements. 


Here are some of the new or improved features: 


Foreword 
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= Improved and comprehensive Guide to Programming, Advanced Interface 
Design Guide, Reference, and Tools manuals. 

= More source-code examples for hands-on learning. 

= Improved tools for editing visual resources. 


‘m New online help-engine facility so you can include a Help system with your 
applications. 


= The Microsoft CodeView® for Windows debugger—the powerful yet easy- 
to-use source-code debugger for any Windows application. 


= New code-execution profiler and segment-swapping analysis facility. 
Take advantage of the success of the Microsoft Windows environment—use the 


Microsoft Windows Software Development Kit to develop powerful, feature-rich 
graphical applications. 


Oiher Recommended Reading 


The following books are recommended for efficient Windows programming and 
are available from Microsoft Press®: 


= Programming Windows. Charles Petzold. 862 pages, softcover. An updated 
second edition will be available in October 1990. 


= Windows: Programmer’ s Problem Solver. Richard Wilton. 400 pages, soft- 
cover. Available November 1990. 


= Microsoft C Run-Time Library Reference. Covers version 6. Microsoft 
_ Corporation. 852 pages, softcover. 
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DDE Messages 


Introduction 


Application Programming Interface 


This manual describes the application programming interface (API) of the 
Microsoft ® Windows ™ presentation manager. The API contains the functions, 
messages, data structures, data types, statements, and files that application 
developers use to create programs that run with Windows. 


The API can be thought of as a set of tools which, when properly used, creates a 
Windows application that is portable across a variety of computers. 


Windows Features 


A Windows application can take advantage of a number of features provided by 
the API. These features include the following: 


m= Shared display, memory, keyboard, mouse, and system timer 
= Data interchange with other applications 

= Device-independent graphics 

= Multitasking 


m Dynamic linking 


Windows allows applications, running simultaneously on the system, to share 
hardware resources; application developers do not need to write specific code to 
accomplish this complex task. 


The clipboard, another Windows feature, acts as a place for data interchange be- 
tween applications. The information sent between applications can be in the form 
of text, bitmaps, or graphic operations. Windows provides a number of functions 
and messages that regulate the transmission of information with the clipboard. 
These functions and the corresponding messages are part of the window manager 
interface, one of several libraries in the API. 


Windows contains functions that an application can use for device-independent 
graphic operations. These functions create output that is compatible with raster 
displays and printers of varying resolution, as well as with a number of vector 
devices (plotters). These functions are part of the graphics device interface 
(GDIJ), the second of the API libraries. ; 
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Windows provides multitasking, which means that several applications can run 
simultaneously. The functions that affect multitasking and memory management 
in general are part of the system services interface, the third API library. 


Because of the memory limitations imposed by DOS, it is important to keep 
applications as compact as possible. Windows accomplishes this compaction 
through dynamic linking and the use of discardable code, which allows an appli- 
cation to load and execute a subset of the library of functions at run time. Only a 
single copy of a library is necessary, no matter how many applications access it. 


Window Manager Interface 


The window manager interface contains the functions that create, move, and alter 
a window, the most basic element in a Windows application. A window is a rec- 
tangular region that contains graphic representations of user input, input options, 
and system output. 


Windows is a menu-driven environment; menus are the principal means of pre- 
senting options to a user from within an application. The functions that create 
menus, alter their contents, and obtain the status of menu items are also part of 
the window manager interface. 


The window manager interface also contains functions that create system output. 
An example of this output is the dialog box that applications use to request user 
input and to display information. 


The window manager interface also contains messages and the functions that 
process them. A message is a special data structure that contains information 
about changes within an application. These changes include keyboard, mouse, 
and timer events, as well as requests for information or actions that an applica- 
tion should carry out. 


Window Manager Interface Function Groups 


The following list describes the function groups found in the window manager in- 
terface: 


= Message functions 

= Information functions 

= Window-creation functions 

= System functions 

= Display and movement functions 
= Clipboard functions 


= Error functions 
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= Input functions 

= Caret functions 

= Hardware functions 

= Cursor functions 

= Painting functions 

™ Hook functions 

m= Dialog functions 

= Property functions 

= Scrolling functions 

= Rectangle functions 


= Menu functions 


Graphics Device Interface 


The graphics device interface (GDI) contains the functions that perform device- 
independent graphic operations within a Windows application. These functions 
create a wide variety of line, text, and bitmap output on a number of different out- 
put devices. GDI allows an application to create pens, brushes, fonts, and bit- 
maps for specific output operations. The following figure shows a sample of text, 
line, and bitmap output from Microsoft Windows Paintbrush™, an application 
that was created with GDI functions: 
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Paintbrush - TOOLS.PCX 
View Font Style Size Pick Options Help 


The one that got away 


Text, Line and Bitmap Output 


Graphics Device Interface Function Groups 


The following list describes the function groups found in GDI: 


= Device-context functions 

= Ellipse and polygon functions | 
= Drawing-tool functions 

m Bitmap functions 

= Drawing-attribute functions 
= Text functions 

= Mapping functions 

= Font functions 

= Coordinate functions 

= Metafile functions 

™ Region functions 


= Printer-escape functions 
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= Clipping functions 
= Environment functions 
= § Line-output functions 


m= System functions 


System Services Interface 


The system services interface contains the functions that access code and data in. 
modules, allocate and manage memory (both local and global), manage tasks, 
load program resources, translate strings from one character set to another, alter 
the Windows initialization file, assist in system debugging, carry out communica- 
tions through the system’s I/O ports, create and open files, and create sounds 
using the system’s sound generator. 


System Services Interface Function Groups 


The following list describes the function groups found in the system services in- 
terface: 

= Module-management functions 
= § Initialization-file functions 

= Memory-management functions 
= Communication functions 

= Task functions 

= Sound functions 

m Resource-management functions 
= Utility functions 

= String-translation functions 

m File I/O functions 

= Atom-management functions 


m™ System functions 
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Naming Conventions 


Many Windows functions have been named with a verb-noun model to help you 
remember and become familiar with the function. The function name indicates 
both what the function does (verb) and the target of its action (noun). All func- 
tion names begin with an uppercase letter. If the name is composed of several 
words, each word begins with an uppercase letter and all words are adjoined (no 
spaces or underscore characters separate the words). Some examples of function 
names are shown below: 


= CreateWindow 


RegisterClass 
SetMapMode 


Parameter Names 


Most parameters and local variables have a lowercase prefix that indicates the 
general type of the parameter, followed by one or more words that describe the 
content of the parameter. The standard prefixes used in parameter and variable 
names are defined below: 


Prefix Meaning 

b Boolean (a nonzero value means true, zero means 
false) 

c Character (a one-byte value) 

dw Long (32-bit) unsigned integer 

f Bit flags packed into a 16-bit integer 

h 16-bit handle 

l Long (32-bit) integer 

lp Long (32-bit) pointer 

n Short (16-bit) integer 

P Short (16-bit) pointer 

pt x- and y-coordinates packed into an unsigned 32-bit 
integer 

rgb RGB color value packed into a 32-bit integer 


w Short (16-bit) unsigned integer 
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If no lowercase prefix is given, the parameter is a short integer whose name is 
descriptive. 


Some examples of parameter and variable names are shown as follows: 


bIconic ptXY 
fAction rgbColor 
hWnd Height 
IpString Xx 

nBytes Width 
pMsg Y 


Windows Calling Convention 


Windows uses the same calling convention used by Microsoft Pascal. 
Throughout this manual, this calling convention will be referred to as the Pascal 
calling convention. The Pascal calling convention entails the following: 


= Parameters are pushed onto the stack in the order in which they appear in the 
function call. 


« The code that restores the stack is part of the called function (rather than the 
calling function). 


This convention differs from the calling convention used in other languages, such 
as C. In C, parameters are pushed onto the stack in reverse order, and the calling 
function is responsible for restoring the stack. 


When developing Windows applications in a language that does not ordinarily 
use the Pascal calling convention, such as C, you must ensure that the Pascal cal- 
ling convention is used for any function that is called by Windows. In C, this re- 
quires the use of the PASCAL key word when the function is declared. 


Manual Overview 


This manual gives the Windows-application developer general as well as detailed 
information about Windows functions, messages, data types, resource-compiler 
statements, assembly-language macros, and file formats. It does not attempt to ex- 
plain how to create a Windows application. Rather, this manual provides detailed 
descriptions of each component of the Windows API for readers who already 
have a basic understanding of Windows programming. 
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This manual is divided into two volumes. The following sections describe the 
purpose and contents of each volume. 


Volume 1 


Volume 1 contains reference information describing the Windows functions and 
messages. It is made up of six chapters: 


Chapter 1, “Window Manager Interface Functions,” categorizes window- 
manager functions into their related groups and briefly describes individual func- 
tions. This chapter also supplies additional information about particular function 
groups, including definitions of new terms and descriptions of models that are 
unique to Windows. This chapter is designed to assist the application developer 
who is new to Windows or who has questions about a particular group of 
Windows functions. | 


Chapter 2, “Graphics Device Interface Functions,” categorizes the functions that 
perform device-independent graphics operations in the Windows environment, 
provides brief descriptions of the functions, and explains the most important fea- 
tures of the Windows graphics interface. 


Chapter 3, “System Services Interface Functions,” categorizes the various utility 
functions that perform services not directly related to managing a window or pro- 
ducing graphical output. 


Chapter 4, “Functions Directory,” contains an alphabetical list of Windows func- 
tions. The documentation for each function gives the syntax, states the function’s 
purpose, lists its input parameters, and describes its return value. For some func- 
tions, additional information the developer needs in order to use those functions 
is given. 


Chapter 5, “Messages Overview,” categorizes messages into their related groups 
and briefly describes individual messages. This chapter also supplies additional 
information about particular message groups, including definitions of new terms 
and descriptions of models that are unique to Windows. This chapter is designed 
to assist the application developer who is new to Windows or who has questions 
about a particular group of Windows messages. 


Chapter 6, “Messages Directory,” contains an alphabetical list of Windows mes- 
sages. The documentation for each message states the message’s purpose, lists its 
input parameters, and describes its return value (if one exists). For some mes- 
sages, additional information the developer needs in order to use those messages 
is given. 


Volume 2 


Volume 2 contains reference material for other components of the Windows API. 
It contains nine chapters and five appendixes: 


Chapter 7, “Data Types and Structures,” contains a table of data types and an al- 
phabetical list of structures found in Windows. 
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Chapter 8, “Resource Script Statements,” describes the statements that define 
resources which the Resource Compiler adds to an application’s executable file. 
The statements are arranged according to functional groups. 


Chapter 9, “File Formats,” describes the formats of five types of files: bitmap 
files, icon resource files, cursor resource files, clipboard files, and metafiles. 
Each description gives the general file structure and information about specific 
parts of the file. 


Chapter 10, “Module-Definition Statements,” describes the statements contained 
in the module-definition file that defines the application’s contents and system re- 
quirements for the LINK program. 


Chapter 11, “Binary and Ternary Raster-Operation Codes,” describes the raster 
operations used for line output and those used for bitmap output. 


Chapter 12, “Printer Escapes,” lists the printer escapes that are available in 
Windows. 


Chapter 13, “Assembly-Language Macros Overview,” categorizes and briefly de- 
scribes the Windows assembly-language macros which provide a simplified inter- 
face to the function and segment conventions of high-level languages. 


Chapter 14, “Assembly-Language Macros Directory,” lists the assembly-lan- 
guage macros alphabetically and, for each macro, provides a detailed description 
and one or more examples of how to use it in a program. 


Chapter 15, “Windows DDE Protocol Definition,” contains an alphabetical 
listing and description of the Windows messages which comprise the Windows 
Dynamic Data Exchange protocol. 


Appendix A, “Virtual-Key Codes,” lists the symbolic names and hexadecimal 
values of Windows virtual-key codes and includes a brief description of each key. 


Appendix B, “RC Diagnostic Messages,” contains a listing of Resource Com- 
piler error messages and provides a brief description of each message. 


Appendix C, “Windows Debugging Messages,” contains a listing of Windows de- 
bugging messages and provides a brief description of each message. 


Appendix D, “Character Tables,” shows the layout of the ANSI character set and 
the IBM PC Extended Character set. 


Appendix E, “32-Bit Memory Management DLL,” describes how to implement a 
32-bit flat memory model for your application. 
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Document Conventions 


_ Throughout this manual, the term “DOS” refers to both MS-DOS® and PC- 
DOS, except when noting features that are unique to one or the other. 


The following document conventions are used throughout this manual: 


Convention 


Bold text 


() 


Italic text 


Monospaced type 


BEGIN 


END 


Description of Convention 


Bold letters indicate a specific term or punctua- 
tion mark intended to be used literally: 
language key words or functions (such as 
EXETYPE or CreateWindow), DOS com- 
mands, and command-line options (such as 
/Zi). You must type these terms and punctua- 
tion marks exactly as shown. However, the use 
of uppercase or lowercase letters is not always 
significant. For instance, you can invoke the 
linker by typing either LINK, link, or Link at 
the DOS prompt. 


In syntax statements, parentheses enclose one 
or more parameters that you pass to a function. 


Words in italics indicate a placeholder; you are 
expected to provide the actual value. For ex- 
ample, the following syntax for the 
SetCursorPos function indicates that you must 
substitute values for the X and Y coordinates, 
separated by a comma: 


SetCursorPos(X, Y) 


Code examples are displayed in a nonpropor- 
tional typeface. 


Vertical ellipses in program examples indicate 
that a portion of the program is omitted. 


{ 


Ellipses following an item indicate that more 
items having the same form may appear. In the 
following example, the horizontal ellipses indi- 
cate that you can specify more than one 
breakaddress for the g command: 


g [[=startaddress]| [breakaddress]]... 
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SMALL CAPITAL LETTERS 


Double brackets enclose optional fields or palay 
meters in command lines and syntax 
statements. In the following example, option 
and executable-file are optional parameters of 
the RC command: 


RC [option] filename \[executable-file]| 


A vertical bar indicates that you may enter one 
of the entries shown on either side of the bar. 
The following command-line syntax illustrates 
the use of a vertical bar: 


DB [address | range] 


The bar indicates that following the Dump 
Bytes command (DB), you can specify either 
an address or a range. 


Quotation marks set off terms defined in the 
text. 


Curly braces indicate that you must specify 
one of the enclosed items. 


Small capital letters indicate the names of keys 
and key sequences, such as: 


ALT + SPACEBAR 


A box containing a Microsoft Windows ver- 
sion number indicates that a function, message, 
or data structure is compatible only with the 
specified version and later versions. 


Microsoft Windows Software Development Kit Documentation Set 


Throughout this documentation set, “SDK” refers specifically to the Microsoft 
Windows Software Development Kit and its contents. The SDK includes the fol- 


lowing manuals: 
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Title 
Installation and 
Update Guide 


Guide to Programming 


Tools 


Reference 


System Application 
Architecture, Common 
User Access: 
Advanced Interface 
Design Guide 


Contents 


Provides an orientation to the SDK, explains how to 
install the SDK software, and highlights the changes 
for version 3.0. 


Explains how to write Windows applications, and 
provides sample applications that you can use as 
templates for writing your own programs. The 
Guide to Programming also addresses some more 
advanced Windows programming topics. 


Explains how to use the software-development tools 
you’ll need to build Windows applications, such as 
debuggers and specialized SDK editors. 


Is a comprehensive guide to all the details of the 
Microsoft Windows application program interface 
(API). The Reference lists in alphabetical order all 
the current functions, messages, and data structures 
of the API, and provides extensive overviews on 
how to use the API. 


Provides guidelines and recommendations for writ- 
ing programs that look and act consistently with 
other Microsoft Windows applications. 


Part || Windows Functions 


Part 1 describes the functions which are the core of the Windows application pro- 
grammer interface (API). You use these functions as part of a C- or assembly- 
language program to create an application that takes advantage of Windows’ 
user-interface, graphics and multitasking capabilities. 


CHAPTERS 


1 ~~ Window Manager Interface Functions 
2 ~~ Graphics Device Interface Functions 
3 System Services Interface Functions 
4 ~ Functions Directory 


Chapter || Window Manager Interface 
7 Functions 


This chapter describes the Microsoft Windows functions that process messages, 
create, move, or alter a window, or create system output. These functions consti- 
tute the window manager interface. 


This chapter describes the following topics: 


= Message functions 

= Window-creation functions 
= Display and movement functions 
= Input functions 

m= Hardware functions 

= Painting functions 

m Dialog-box functions 

= Scrolling functions 

= Menu functions 

a Information functions 

m= System functions 

= Clipboard functions 

= Error functions 

= Caret functions 

= Cursor functions 

= Hook functions 

= Property functions 


™ Rectangle functions 
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1.71 Message Functions 


Message functions read and process Windows messages in an application’s 
queue. Messages represent a variety of input to a Windows application. A 
message is a data structure that contains a message identifier and message para- 
meters. The content of the parameters varies with the message type. The follow- 
ing list briefly describes each function: 


Function 
CallWindowProc 
DispatchMessage 


GetMessage © 
GetMessagePos 
GetMessageTime 


InSendMessage 


PeekMessage 


PostAppMessage 
PostMessage 
PostQuitMessage 
ReplyMessage 
SendMessage 
SetMessageQueue 


TranslateAccelerator 
TranslateMDISysAccel 
TranslateMessage 


WaitMessage 


Description 
Passes message information to the specified function. 


Passes a message to a window function of the 
specified window. 


Retrieves a message from the specified range of 
messages. 


Returns the position of the mouse at the time the last 


message was retrieved. 


Returns the time at which the last message was 
retrieved. 


Determines whether the current window function is 
processing a message passed to it through a call to 
the SendMessage function. 


Checks the application queue and places the 
message appropriately. 


_ Posts a message to the application. 


Places a message in the application queue. 

Posts a WM_QUIT message to the application. 
Replies to a message. 

Sends a message to a window or windows. 
Creates a new message queue of a different size. 


Processes keyboard accelerators for menu com- 
mands. 


Processes multiple document interface (MDI) child 
window command accelerators. 


Translates virtual key-stroke messages into character 
messages. 


Yields control to other applications. 
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Function Description 
WinMain Serves as an entry point for execution of a Windows 
application. 


1.1.1 Generating and Processing Messages 


Windows generates a message at each input event, such as when the user moves 
the mouse or presses a keyboard key. Windows collects these input messages in a. 
system-wide queue and then places these messages, as well as timer and paint 
messages, in an application’s queue. The application queues are first-in/first-out 
queues that belong to individual applications; however, timer and paint messages 
are held in the queue until the application has processed all other messages. 
Windows places messages that belong to a specific application in that applica- 
tion’s queue. The application then reads the messages by using the GetMessage 
function and dispatches them to the appropriate window function by using the 
DispatchMessage function. 


Windows sends some messages directly to an application’s window function, 
without placing them in the application queue. Such messages are called un- 
queued messages. In general, an unqueued message is any message that affects 
the window only. The SendMessage function sends messages directly to a 
window. 


For example, the CreateWindow function directs Windows to send a 
WM_CREATE message to the window function of the application and to wait 
until the message has been processed by the window function. Windows sends 
this message directly to the function and does not place it in the application 
queue. 


Although most messages are generated by Windows, applications can create their 
own messages and place them in the application queues of other applications. 


An application can pull messages from its queue by using the GetMessage func- 
tion. This function searches the application queue for messages and, if a message 
exists, returns the top message in the application queue. If the application queue 
is empty, GetMessage waits for a message to be placed in the queue. While wait- 
ing, GetMessage relinquishes control to Windows, allowing other applications to 
take control and process their own messages. 


Once a main function has a message from a queue, it can dispatch the message to 
a window function by using the DispatchMessage function. This function directs 
Windows to call the window function of the window associated with the 
message, and then passes the content of the message as function arguments. The 
window function can then process the message and carry out any requested 
changes to,the window. When the window function returns, Windows returns 
control to the main function. The main function can then pull the next message 
from the queue. . 
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NOTE Unless noted otherwise, Windows can send messages in any sequence. An applica- 
tion should not rely on receiving messages in a particular order. 


Windows generates a virtual-key message each time the user presses a keyboard 
key. The virtual-key message contains a virtual-key code that defines which key 
was pressed, but does not define the character value of that key. To retrieve the 

character value, the main function must translate the virtual-key message by 
using the TranslateMessage function. This function puts another message with 
an appropriate character value in the application queue. The message can then be 
dispatched to a window function. 


1.17.2 Translating Messages 


In general, a main function should use the TranslateMessage function to trans- 
late every message, not just virtual-key messages. Although TranslateMessage 
has no effect on other types of messages, it guarantees that any keyboard input is 
translated correctly. 


The following program fragment illustrates the typical loop that a main function 
uses to pull messages from the queues and dispatch them to window functions: 


int PASCAL WinMain(hInstance, hPrevInstance, IpCmdLine, nShowCmd) 
HANDLE hInstance; 
HANDLE hPrevinstance; 
LPSTR 1pCmdLine; 
int nShowCmd; 
{ 
MSG msg; 


while (GetMessage((LPMSG)&msg, NULL, @, @)) 
{ 
TranslateMessage( (LPMSG)&msq) ; 
DispatchMessage((LPMSG)&msqg) ; 
} 
exit(msg.wParam) ; 


Applications that use accelerator keys must load an accelerator table from 

the resource file by using the LoadAccelerator function, and then translate 
keyboard messages into accelerator-key messages by using the Translate- 
Accelerator function. The main loop for applications that use accelerator keys 
should have the following form: 


while (GetMessage((LPMSG)&msg, (HWND)NULL, @, @)) 
{ 
if (TranslateAccelerator(hWindow, hAccel, ((LPMSG)&msg) == @) 
{ 


Window Manager Interface Functions 1-5 


TranslateMessage((LPMSG)&msg); 
DispatchMessage((LPMSG)&msg) ; 
} 
} 
exit(msg.wParam) ; 


The TranslateAccelerator function must appear before the standard Trans- 
lateMessage and DispatchMessage functions. Furthermore, since Trans- 
lateAccelerator automatically dispatches the accelerator message to the 
appropriate window function, the TranslateMessage and DispatchMessage 
functions should not be called if TranslateAccelerator returns a nonzero value. 


1.1.3 Examining Messages 


An application can use the PeekMessage function when it checks the queues for 
messages but does not want to pull the message from the queue. The function re- 
turns a nonzero value if a message is in the queue, and lets the application re- 
trieve the message and process it without going through the application’s main 
loop. 


Typically, an application uses PeekMessage to check periodically for messages 
when the application is carrying out a lengthy operation, such as processing input 
and output. For example, this function can be used to check for messages that ter- 
minate the operation. PeekMessage also gives the application a chance to yield 
control if no messages are present because PeekMessage can yield if no mes- 
sages are in the queue. 


1.1.4 Sending Messages 


The SendMessage and PostMessage functions let applications pass messages to 
their windows or to the windows of other applications. 


The PostMessage function directs Windows to post the message by placing it in 
the application queue. Control returns immediately to the calling application, and 
any action to be carried out as a result of the message does not occur until the 
message is read from the queue. 


The SendMessage function directs Windows to send a message directly to the 
given window function, bypassing the application queue. Windows does not re- 
turn control to the calling application until the window function that receives the 
message processes the message. 


When an application transmits a message, it must send the message by calling 
Send Message if the application relies on the return value of a message. The re- 
turn value of SendMessage is the same as the return value of the function that 
processed the message. PostMessage returns immediately after sending the 
message, so its return value is only a Boolean value indicating whether the 
message was successfully sent and so does not indicate how the message was 
processed. 
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Windows communicates with applications through window messages. The mes- 
sages are passed (sent or posted) to an application’s window function to let the 
function process the messages as desired. Although an application’s main func- 
.tion may read and dispatch window messages, in most cases only the window 
function processes them. 


1.1.5 Avoiding Message Deadlocks 


An application can create a deadlock condition in Windows if it yields control 
while processing a message sent from another application (or by Windows on 
behalf of another application) by means of the SendMessage function. The appli- 

_ cation does not have to yield explicitly. Calling any one of the following func- 
tions can result in the application yielding control: 


= DialogBox 
= DialogBoxIndirect 
= DialogBoxIndirectParam 
= =DialogBoxParam 
= GetMessage 
= MessageBox 
= PeekMessage 
= Yield 
Normally a task that calls SendMessage to send a message to another task will 
not continue executing until the window procedure that receives the message re- 
turns. However, if a task that receives the message yields control, Windows can 


be placed in a deadlock situation where the sending task needs to execute and 
process messages but cannot because it is waiting for SendMessage to return. 


A window function can determine whether a message it receives was sent by 
SendMessage by calling the InSendMessage function. Before calling any of the 
functions listed above while processing a message, the window function should 
‘first call InSendMessage. If InSendMessage returns TRUE, the window func- 
tion must call the ReplyMessage function before calling any function that yields 
control. 


As an alternative, can use a system modal dialog box or message box. Because 
system modal windows prevent other windows from receiving input focus or 
messages, an application should use system modal windows only when necessary. 
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1.2 Window-Creation Functions 


Window-creation functions create, destroy, modify, and obtain information about 
windows. The following list briefly describes each window-creation function: 


Function 


AdjustWindowRect 


AdjustWindowRectEx 


CreateWindow 


CreateWindowEx 


DefDlgProc 


DefFrameProc 


DefMDIChildProc 


DefWindowProc 


DestroyWindow 
GetClassInfo 
GetClassLong 


GetClassName 
GetClassWord 


GetLastActivePopup 


GetWindowLong 
GetWindowWord 
RegisterClass 


Description 


Computes the size of a window to fit a given client 
area. 


Computes the size of a window with extended style 
to fit a given client area... 


Creates overlapped, pop-up, and child windows. 


Creates overlapped, pop-up, and child windows with 
extended styles. 


Provides default processing for those dialog-box 
messages that an application does not process. 


Provides default processing for those multiple docu- 
ment interface (MDI) frame window messages that 
an application does not process. 


Provides default processing those for MDI child 
window messages an that application does not 
process. 


Provides default processing for those window mes- 
sages that an application does not process. 


Destroys a window. 
Retrieves information about a specified class. 


Retrieves window-class information from a WND- 
CLASS structure. 


Retrieves a window-class name. 


Retrieves window-class information from a WND- 
CLASS structure. 


Determines which popup window owned by another 
window was most recently active. 


Retrieves information about a window. 
Retrieves information about a window. 


Registers a window class. 
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Function Description 

SetClassLong Replaces information ina WNDCLASS structure. 

SetClassWord Replaces information ina WNDCLASS structure. 

SetWindowLong Changes a window attribute. 

SetWindowWord Changes a window attribute. 

UnregisterClass ee a window class from the window-class 
table. 


1.2.1 Window Classes 


A window class is a set of attributes that defines how a window looks and be- 
haves. Before an application can create and use a window, it must define and 
register a window class for that window. An application registers a class by pass- 
ing values for each element of the class to the RegisterClass function. Any num- 
ber of window classes can be registered. Once a class has been registered, 
Windows lets the application create any number of windows belonging to that 
class. The registered class remains available until it is deleted or the application 
terminates. 


Although the complete window class consists of many elements, Windows re- 
quires only that an application supply a class name, an address to the window pro- 
cedure that will process all messages sent to windows belonging to this class, and 
an instance handle that identifies the application that registered the class. The 
other elements of the window class define default attributes for windows of the 
class, such as the shape of the cursor and the content of the menu for the window. 


There are three types of window classes. They differ in scope and when they are 
created and destroyed. 


System Global Classes 


Windows creates system global classes when it starts. These classes are available 
for use by all applications at all times. Because Windows creates system global 
classes on behalf of all applications, an application cannot create or destroy any 
of these classes. Examples of system global classes include edit-control and list- 
box control classes. 


Application Global Classes 


An application or (more likely) a library creates an application global class by 
specifying the CS_GLOBALCLASS style for the class. Once created, it is 
globally available to all applications within the system. Most often, a library 
creates an application global class so that applications which call the library can 
use the class. Windows destroys an application global class when the application 
or library that created it terminates. For this reason, it is essential that all applica- 
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tions destroy all windows using that class before the library or application that 
created the class terminates. 


Application Local Classes 


An application local class is any window class created by an application for its 
exclusive use. This is the most common type of class created by an application. 


1.2.2 How Windows Locates a Class 


When an application creates a window with a specified class, xangows uses the 
following algorithm to find the class: 


1. Windows searches for a local class of the specified name. 


2. If Windows does not find a local class with the name, then it searches the 
application global class list. 


3. If Windows does not find the name in the application global class list, then it 
searches the system global class list. 


This procedure is used for all windows created by the application, including 
windows created on the application’s behalf, such as dialog controls. It is 
possible, then, to override system global classes without affecting other applica- 
tions. 


1.2.3 How Windows Determines the Owner of a Class 


Windows determines class ownership from the hInstance field of the WND- 
CLASS structure passed to the RegisterClass function when the application or li- 
brary registers the class. For Windows libraries, this must be the instance handle 
of the library. When the application that registered the class terminates or the li- 
brary that registered the class is unloaded, the class is destroyed. For this reason, 
all windows using the class must be destroyed before the application or library 
terminates. 


1.2.4 Registering a Window Class 


When Windows registers a window class, it copies the attributes into its own 
memory area. Windows uses the internally stored attributes when an application 
refers to the window class by name; it is not necessary for the application that 
originally registered the class to keep the structure available. 
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1.2.5 Shared Window Classes 


Applications must not share registered classes with other applications. Some 
information in a window class, such as the address of the window function, is 

_ specific to a given application and cannot be used by other applications. 
However, applications can share an application global class. See “Application 
Global Classes,” in Section 1.2.1 for more information. 


Although applications must not share registered classes, different instances of the 
same application can share a registered class. Once a window class has been 
registered by an application, it is available to all subsequent instances of that 
application. This means that new instances of an application do not need to, and 
should not, register window classes that have been registered by previous in- 
stances. 


1.2.6 Predefined Window Classes 


Windows provides several predefined window classes. These classes define 
special control windows that carry out common input tasks that let the user input 
text, direct scrolling, and select from a list of names. The predefined window 
classes are available to all applications and can be used any number of times to 
create any number of these control windows. 


1.2.7 Elements of a Window Class 


The elements of the window class define the default behavior of the windows 
created from that class. The application that registers the window class assigns 
elements to the class by setting appropriate fields ina WNDCLASS data struc- 
ture and passing the structure to the RegisterClass function. An application can 
retrieve information about a given window class with the GetClassInfo function. 


Table 1.1 shows the window class elements: 


Table 1.1 Window Class Elements 


Element Purpose 

Class name Distinguishes the class from other registered 
classes. 

Window-function address Points to the function that processes all messages 


that are sent to windows in the class, and defines 
the behavior of the window. 


Instance handle | Identifies the application that registered the class. 


Class cursor Defines the shape of the cursor when the cursor is 
in a window of the class. 
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Table 1.1 =©Window Class Elements (continued) 


Element Purpose 

Class icon Defines the shape of the icon Windows displays 
when a window belonging to the class is closed. 

Class background brush Defines the color and pattern Windows uses to fill 
the client area when the window is opened or 
painted. 

Class menu Specifies the default menu used for any window 


in the class that does not explicitly define a menu. 


Class styles Defines how to update the window after moving 
or resizing, how to process double-clicks of the 
mouse, how to allocate space for the display con- 
text, and other aspects of the window. 


Class extra Specifies the amount of memory (in bytes) that 
Windows should reserve at the end of the class 
data structure. 

Window extra Specifies the amount of memory (in bytes) that 
Windows should reserve at the end of any 
window structure an application creates with this 
class. 


The following sections describe the elements of a window class and explain the 
default values for these elements if no explicit value is given when the class is 
registered. 


Class Name 


Every window class needs a class name. The class name distinguishes one class 
from another. An application assigns a class name to the class by setting the 
IpszClassName field of the WNDCLASS structure to the address of a null- 
terminated string that contains the name. 


In the case of an application global class, the class name must be unique to distin- 
guish it from other application global classes. If an application registers another 
application global class with the name of an existing application global class, the 
RegisterClass function returns FALSE, indicating failure. A conventional 
method for ensuring this uniqueness is to include the application name in the 
name of the application global class. 


The class name must be unique among all the classes registered by an applica- 
tion. An application cannot register an application local class and an application 
global class with the same class name. 
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Window-Function Address 


Every class needs a window-function address. The address defines the entry 
point of the window function that is used to process all messages for windows in 
the class. Windows passes messages to the function when it wants the window to 
carry out tasks, such as painting its client area or responding to input from the 
user. An application assigns a window function address by copying the address 
to the IpfnWndProc field of the WNDCLASS structure. The window function 
must be exported in the module-definition (.DEF) file. See Chapter 10, “Module- 
Definition Statements,” in Reference, Volume 2, for more information on ex- 
porting functions. 


For details about the window function, see Section 1.2.13, “Window Function.” 


Instance Handle 


Every window class needs an instance handle to identify the application that 
registered the class. As a multitasking system, Windows lets several applications 
run at the same time, so it needs instance handles to keep track of all applica- 
tions. Windows assigns a unique handle to each copy of a running application. 


Windows passes an instance handle to an application when the application first 
begins operation. The application assigns this instance handle to the class by 
copying it to the hInstance field of the WNDCLASS structure. 


Class Cursor. 


The class cursor defines the shape of the cursor when the cursor is in the client 
area of a window in the class. Windows automatically sets the cursor to the given 
shape as soon as the cursor enters the window’s client area, and ensures that the 
cursor keeps that shape while it remains in the client area. To assign a cursor 
shape to a window class, an application typically loads the shape from the appli- 
cation’s resources by using the LoadCursor function, and then assigns the 
returned cursor handle to the hCursor field of the WNDCLASS structure. 


Windows does not require a class cursor. If a class cursor is not defined, 
Windows assumes that the window will set the cursor shape each time the cursor 
moves into the window. 


Class Icon 


The class icon defines the shape of the icon used when the window of the given 

class is minimized. To assign an icon to a window class, an application typically 
loads the icon from the application’s resources by using the LoadIcon function, 
and then assigns the returned icon handle to the hIcon field of the WNDCLASS 
structure. 


Windows does not require a class icon. If a class icon is not defined, Windows 
assumes the application will draw the icon whenever the window is minimized. 
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In this case, Windows sends appropriate messages to the window procedure, 
requesting that the icon be painted. 


Class Background Brush 


A class background brush is the brush used to prepare the client area of a 
window for subsequent drawing by the application. Windows uses the brush 

to fill the client area with a solid color or pattern, thereby removing all previous 
images from that location whether they belonged to the window or not. | 


To assign a background brush to a class, an application typically creates a brush 
by using the appropriate functions from GDI, and then assigns the returned brush 
handle to the hbrBackground field of the WNDCLASS structure. 


Instead of creating a brush, an application can use a standard system color by 
setting the field to one of the following color values: 


=m COLOR_ACTIVECAPTION 

= COLOR_APPWORKSPACE 

=» COLOR_BACKGROUND 

= COLOR_BTNFACE 

= COLOR_BTNSHADOW 

= COLOR_BTNTEXT 

= COLOR_CAPTIONTEXT 

a COLOR_GRAYTEXT 

= COLOR_HIGHLIGHT 

# COLOR_HIGHLIGHTTEXT 

= COLOR_INACTIVECAPTION 
= COLOR_MENU 

= COLOR_MENUTEXT 

= COLOR_SCROLLBAR 

= COLOR_WINDOW 

= COLOR_WINDOWFRAME 

= COLOR_WINDOWTEXT 

To use a standard system color, the application must increase the background- 


color value by one. For example, COLOR_BACKGROUND + 1 is the system 
background color. 


1-14 Reference — Volume 1 


Class Menu 


A class menu defines the default menu to be used by the windows in the class if 
no explicit menu is given when the windows are created. A menu is a list of com- 
mands that appears at the top of a window, under the title bar, from which a user 
can select actions for the application to carry out. To assign a menu to a class, an 
application sets the lpszMenuName field of the WNDCLASS structure to the 
address of a null-terminated string that contains the resource name of the menu. 
The menu is assumed to be a resource in the given application. Windows auto- 
matically loads the menu when it is needed. Note that if the menu resource is 
identified by an integer and not by a name, the IpszMenuName field can be set 
to that integer value by applying the MAKEINTRESOURCE macro before 
assigning the value. 


Windows does not require a class menu. If a menu is not given, Windows as- 
sumes that the windows in the class have no menu bars. Even if no class menu is 
given, an application can still define a menu bar for a window when it creates the 
window. 


Windows does not allow menu bars with child windows. If a menu is given anda 
child window is created using the class, the menu is ignored. 


1.2.8 Class Styles 


The class styles define additional elements of the window class. Two or more 
styles can be combined by using the bitwise OR operator. Table 1.2 lists the class 
styles: 


Table 1.2 Window Class Styles 


Style Description 

CS_BYTEALIGNCLIENT Aligns the window’s client area on a byte 
boundary (in the x direction). 

CS_BYTEALIGNWINDOW Aligns the window on a byte boundary (in the x 
direction). 

CS_CLASSDC Allocates one display context to be shared by 
all windows in the class. 

CS_DBLCLKS Sends double-click messages to the window 


function. 
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Table 1.2 Window Class Styles (continued) 


Style 


CS_GLOBALCLASS 


CS_HREDRAW 


CS_NOCLOSE ~ 
CS_OWNDC 
CS_PARENTDC 


CS_SAVEBITS 


CS_VREDRAW 


Description 


Specifies that the window class is an applica- 
tion global class. An application global class is 
created by an application or library and is avail- 
able to all applications. The class is destroyed 
when the application or library that created the 
class terminates; it is essential, therefore, that 
all windows created with the application global 
class be closed before this occurs. 


Requests that the entire client area be redrawn 
if a movement or adjustment to the size 
changes the width of the client area. 


Inhibits the close option on the System menu. 


Allocates a unique display context for each 
window in the class. 


Gives the parent window’s display context to ' 
the window class. 


Saves the portion of the screen image that is ob- 
scured by a window; Windows uses the saved 
bitmap to re-create the screen image when the 
window is removed. Windows displays the bit- 
map at its original location and does not send 
WM_PAINT messages to windows which had 
been obscured by the window if the memory 
used by the bitmap has not been discarded and 
if other screen actions have not invalidated the 
stored image. 


Requests that the entire client area be redrawn 
if a movement or adjustment to the size 
changes the height of the client area. 


To assign a style to a window class, an application assigns the style value to the 
style field of the WNDCLASS structure. 
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1.2.9 Internal Data Structures 


Windows maintains internal data structures for each window class and window. 
These structures are not directly accessible to applications but can be examined 
and modified by using the following functions: 


= GetClassInfo 

= GetClassLong 

= GetClassName 

m GetClassWord 

= GetWindowLong 
= GetWindowWord 
m SetClassLong 

Be SetClassWord 

= SetWindowLong 
= SetWindowWord 


Section 1.2.10 describes some ways in which a window class or window can be 
modified. 


7.2.10 Window Subclassing 


A subclass is a window or set of windows that belong to the same window class, 
and whose messages are intercepted and processed by another window function 
(or functions) before being passed to the class window function. 


To create the subclass, the SetWindowLong function is used to change the 
window function associated with a particular window, causing Windows to call 
the new window function instead of the previous one. Any messages not 
processed by the new window function must be passed to the previous window 
function by calling the CallWindowProc function. This allows Windows to 
create a chain of window functions. The address of the previous window function 
can be retrieved by using the GetWindowLong function before using Set Win- 
dowLong. 


Similarly, the SetClassLong function changes the window function associated 
with a window class. Any window that is subsequently created with that class 
will be associated with the replacement window function for that class, as will 
the wirdow whose handle is passed to SetClassLong. Other existing windows 
that were previously created with the class are not affected, however. 
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When you subclass a window or class of windows, you must export the replace- 
ment window procedure in your application’s definition file, and you must create 
the address of the procedure which you pass to SetWindowLong or Set- 
ClassLong by calling the MakeProcInstance function. 


NOTE Anapplication should not attempt to create a window subclass for standard 
Windows controls such as combo boxes and buttons. 


1.2.11 Redrawing the Client Area 


When a window is moved, Windows automatically copies the contents of the 
client area to the new location. This saves time because a window does not have 
to recalculate and redraw the contents of the client area as part of the move. If the 
window moves and changes size, Windows copies only as much of the previous 
client area as is needed to fill the new location. If the window increases in size, 
Windows copies the entire client area and sends a WM_PAINT message to the 
window to fill in the newly exposed areas. When a window is moved, Windows 
assumes the contents of the client area remain valid and can be copied without 
modification to the new location. 


For some windows, however, the contents of the client area are not valid after a 
move, especially if the move includes a change in size. For example, a clock 
application whose window must always contain the complete image of the clock 
has to redraw the window anytime the window changes size, and has to update 
the time after the move. To prevent the windows from copying the previous con- 
tents of the client area, a window should specify the CS_VREDRAW and 
CS_HREDRAW styles in the window class. 


1.2.12 Class and Private Display Contexts 


A display context is a special set of values that applications use for drawing in 
the client area of their windows. Windows requires a display context for each 

window on the system display, but allows some flexibility in how that display 
context is stored and treated by the system. 


If no explicit display-context style is given, Windows assumes that each window 
will use a display context retrieved from a pool of contexts maintained by 
Windows. In such cases, each window must retrieve and initialize the display 
context before painting, and then free it after painting. 


In order not to retrieve a display context each time it wants to paint in a window, 
an application can specify the CS_OWNDC style for the window class. This 
class style directs Windows to create a private display context, that is, to allocate 
a unique display context for each window in the class. The application need only 
retrieve the context once, and then use it for all subsequent painting. Although 
the CS_OWNDC style is convenient, it must be used carefully because each dis- 
play context occupies approximately 800 bytes of memory in the GDI heap. 
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By specifying the CS_CLASSDC style, an application can have some of the con- 
venience of a private display context without allocating a separate display con- 
text for each window. The CS_CLASSDC style directs Windows to create a 
single class display context, that is, one display context to be shared by all 
windows in the class. An application need only retrieve the display context for a 
window; then as long as no other window in the class retrieves that display con- 
text, the window can continue to use the context. 


Similarly, by specifying the CS_PARENTDC style, an application can create 
child windows that inherit the device context of their parent. 


1.2.13 Window Function 


A window function processes all messages sent to a window in a given class. 
Windows sends messages to a window function when it receives input from the 
user that is intended for the given window, or when it needs information or the 
procedure to carry out some action on its window, such as painting in the client 
area. 


A window function receives input messages from the keyboard, mouse, and 
timer. It receives requests for information, such as a request for the window title. 
It receives reports of changes made to the system by other windows, such as a 
change to the WIN.INI file. It receives messages that give it an opportunity to 
modify the standard system response to certain actions, such as an opportunity to 
adjust a menu before it is displayed. It receives requests to carry out some action 
on its window or client area, such as a request to update the client area. Anda 
window function receives information about its status in relation to other 
windows, such as losing access to the keyboard or becoming the active window. 


Most of the messages a window function receives are from Windows, but it can 
also receive messages from other windows, including windows it owns. These 
messages can be requests for information or notification that a given event has oc- 
curred within another window. 


A window function continues to receive messages from the system and possibly 
other windows in the system until it, or the window function of a parent window, 
or the system destroys the window. Even in the process of being destroyed, the 
window function receives additional messages that give it the opportunity to 
carry out any clean-up tasks before terminating. But once the window is de- 
stroyed, no more messages are passed to the function for that particular window. 
If there is more than one window of the class, however, the window function con- 
tinues to receive messages for the other windows until they, too, are destroyed. 


A window function defines how a given window actually behaves; that is, it de- 
‘fines what response the window makes to commands from the user or system. 
The messages the window function receives from the system contain information 
that the function knows; for example, the user clicked the scroll bar or selected 
the Open command in the File menu, or double-clicked in the client area. The 
window function must examine these messages and determine what action, if 
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any, to take. For example, if the user clicks the scroll bar, the window function 
may scroll the contents of the client area. Windows provides detailed information 
about what happens and provides some tools to carry out tasks, such as drawing 
and scrolling, but the window function must carry out the actual task. 


A window function can also choose not to respond to a given message. If it does 
not respond, the function must give the system the opportunity to respond by 
passing the message to the DefWindowProc function. This function carries out 
default actions based on the given message and its parameters. Many messages, 
especially nonclient-area messages, must be processed, so the DefWindowProc 
function is required in all window functions. 


A window function also receives messages that are really intended to be 
processed by the system. These messages, called nonclient-area messages, in- 
form the function either that the user has carried out some action in a nonclient 
area of the window, such as clicking the title bar, or that some information about 
the window is required by the system to carry out an action, such as for moving 
or adjusting the size of the window. Although Windows passes these messages to 
the window function, the function should pass them to the DefWindowProc 
function and not attempt to process them. In any case, the window procedure 
must not ignore the message or return without passing it to DefWindowProc. 


Window Messages 


A window message is a set of values that Windows sends to a window function 
when it requests some action or informs the window of input. Every message con- 
sists of four values: a handle that identifies the window, a message identifier, a 
16-bit message-specific value, and a 32-bit message-specific value. These values 
are passed as individual parameters to the window function. The window func- 
tion then examines the message identifier to determine what response to make 
and how to interpret the 16- and 32-bit values. 


Windows has a wide variety of messages that it or applications can send to a 
window function. Most messages are sent to a window as a result of a given func- 
tion being executed or as input from the user. 


To send a message to a window procedure, Windows expects the window func- 
tion to have four parameters and use the Pascal calling convention. The follow- 
ing illustrates the window procedure syntax: 


LONG FAR PASCAL WhdProc(hWnd, wMsg, wParam, lParam) 
HWND hWnd; 

WORD wMszg; 

WORD wParam; 

DWORD /Param; 


The hWnd parameter identifies the window receiving the message; the wMsg 
parameter is the message identifier; the wParam parameter is 16 bits of addi- 
tional message-specific information; and /Param is 32 bits of additional informa- 
tion. The window procedure must return a 32-bit value that indicates the result of 
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message processing. The possible return values depend on the actual message 


sent. 


Windows expects to make an intersegment call to the window function, so the 
function must be declared with the FAR attribute. The window-function name 
must be exported by including it in an EXPORTS statement in the application’s 


module-definition file. 


Default Window Function 


The DefWindowProc function is the default message processor for window func- 
tions that do not or cannot process some of the messages sent to them. For most 
window functions, the DefWindowProc function carries out most, if not all, pro- 
cessing of nonclient-area messages. Those are the messages that signify actions 
to be carried out on parts of the window other than the client area. Table 1.3 lists 
the messages DefWindowProc processes and the default actions for each: 


Table 1.3 


Message 


WM_ACTIVATE 
WM_CANCELMODE 


WM_CLOSE 
WM_CTLCOLOR 
WM_ERASEBKGND 


WM_GETTEXT 
WM_GETTEXTLENGTH 


WM_ICONERASEBKGND 
WM_NCACTIVATE 


WM_NCCALCSIZE 
WM_NCCREATE 


WM_NCDESTROY 


Default Actions for Messages 


Default Action 


Sets or kills the input focus. 


Terminates internal processing of standard scroll 
bar input, terminates internal menu processing, 
and releases mouse capture. 


Calls the DestroyWindow function. 


Sets the background and text color and returns a 


‘handle to the brush used to fill the control back- 


ground. 


Fills the client area with the color and pattern 
specified by the class brush, if any. 


Copies the window title into a specified buffer. 


Returns the length (in characters) of the window 
title. 


Fills the icon client area with the background 
brush of the parent window. 


Activates or deactivates the window and draws 
the icon or title bar to show the new state. 


Computes the size of the client area. 


Initializes standard scroll bars, if any, and sets the 
default title for the window. 


Frees any space internally allocated for the 
window title. 


Table 1.3 


Message 


WM_NCHITTEST 


WM_NCLBUTTONDBLCLK 
WM_NCLBUTTONDOWN 
WM_NCLBUTTONUP 
WM_NCMOUSEMOVE 
WM_NCPAINT 

WM_PAINT 


WM_PAINTICON 


WM_QUERYENDSESSION 
WM_QUERYOPEN 
WM_SETREDRAW 


WM_SETTEXT 
WM_SHOWWINDOW 
WM_SYSCHAR 


WM_SYSCOMMAND 
WM_SYSKEYDOWN 
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Default Actions for Messages (continued) 


Default Action 


Determines what part of the window the mouse is 
in. 


Tests the given point to determine the location of 
the mouse and, if necessary, generates additional 
messages. 


Determines whether the left mouse button was 
pressed while the mouse was in the nonclient area 
of a window. 


Tests the given point to determine the location of 
the mouse and, if necessary, generates additional 
messages. 


Tests the given point to determine the location of 
the mouse and, if necessary, generates additional 
messages. 


Paints the nonclient parts of the window. 


Validates the current update region, but does not 
paint the region. 


Draws the window class icon when a window is 
minimized. 

Returns TRUE. 

Returns TRUE. 


Forces an immediate update of information about 
the clipping area of the complete window. 


Sets and displays the window title. 
Opens or closes a window. 


Generates a WM_SYSCOMMAND message for 
menu input. 


Carries out the requested system command. 


Examines the given key and generates a 
WM_SYSCOMMAND message if the key is 
either TAB Or ENTER. 


1.2.14 Window Styles 


Windows provides several different window styles that can be combined to form 
different kinds of windows. The styles are used in the CreateWindow function 
when the window is created. 
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Overlapped Windows 


An overlapped window is always a top-level window. In other words, an over- 
lapped window never has a parent window. It has a client area, a border, and a 
title bar. It can also have a System menu, minimize/maximize boxes, scroll bars, 
and a menu, if these items are specified when the window is created. For 
windows used as a main interface, the System menu and minimize/maximize 
boxes are strongly recommended. 


Every overlapped window can have a corresponding icon that Windows displays 
when the window is minimized. A minimized window is not destroyed. It can be 
opened again by restoring the icon. An application minimizes a window to save 
screen space when several windows are open at the same time. 


You create an overlapped window by using the WS_OVERLAPPED or 
WS_OVERLAPPEDWINDOW style with the CreateWindow function. An 
overlapped window created with the WS_OVERLAPPED style always has a 
caption and a border. The WS_OVERLAPPEDWINDOW style creates an over- 
lapped window with a caption, a thick-frame border, a system menu, and min- 
imize and maximize boxes. 


Owned Windows 


An owned window is a special type of overlapped window. Every owned 
window has an owner. This owner must also be an overlapped window. Being 
owned forces several constraints on a window: 


= An owned window will always be “above” its owner when the windows are 
ordered. Attempting to move the owner above the owned window will cause 
the owned window to also change position to ensure that it will always be 
above its owner. 


= Windows automatically destroys an owned window when it destroys the 
window’s owner. 


= An owned window is hidden when its owner is minimized. 


An application creates an owned window by specifying the owner’s window 
handle as the hWndParent parameter of the CreateWindow function when creat- 
ing a window that has the WS_OVERLAPPED style. 


Dialog boxes are owned windows by default. The function that creates the dialog 
box receives the handle of the owner window as its hWndParent parameter. 


Pop-up Windows 


Pop-up windows are another special type of overlapped window. The main differ- 
ence between a pop-up window and an overlapped window is that an overlapped 
window always has a caption, while the caption bar is optional for a pop-up 
window. Like overlapped windows, pop-up windows can be owned. 
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You create a pop-up window by using the WS_POPUP window style with the 
CreateWindow function. A pop-up window can be opened and closed by using 
the ShowWindow function. 


Child Windows 


A child window is the window style used for windows that are confined to the 
client area of a parent window. Child windows are typically used to divide the 
client area of a parent window into different functional areas. 


You create a child window by using the WS_CHILD window style with the 
CreateWindow function. A child window can be shown and hidden by using the 
ShowWindow function. 


Every child window must have a parent window. The parent window can be an 
overlapped window, a pop-up window, or even another child window. The 
parent window relinquishes a portion of its client area to the child window, and 
the child window receives all input from this area. The window class does not 
have to be the same for each of the child windows in the parent window. This 
means an application can fill a parent window with child windows that look 
different and carry out different tasks. 


A child window has a client area, but it does not have any other features unless 
these are explicitly requested. An application can request a border, title bar, min- 
imize/maximize boxes, and scroll bars for a child window. In most cases, the 
application designs its own features for the child window. 


Although not required, every child window should have a unique integer identi- 
fier. The identifier, given in the menu parameter of the CreateWindow function 
in place of a menu, helps identify the child window when its parent window has 
many other child windows. The child window should use this identifier in any 
messages it sends to the parent window. This is the way a parent window with 
several child windows can identify which child window is sending the message. 


Windows always positions the child window relative to the upper-left corner of 
the parent window’s client area. The coordinates are always client coordinates. 
(For information about mapping, see Section 2.5, “Mapping Functions.”) If all or 
part of a child window is moved outside the visible portion of the parent 
window’s client area, the child window is clipped; that is, the portion outside the 
parent window’s client area is not displayed. . 


A child window is an independent window that receives its own input and other 
messages. Input intended for a child window goes directly to the child window 
and is not passed through the parent window. The only exception is if input to the 
child window has been disabled by the EnableWindow function. In this case, 
Windows passes any input that would have gone to the child window to the 
parent window instead. This gives the parent window an opportunity to examine 
the input and enable the child window, if necessary. 
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Actions that affect the parent window can also affect the child window. The fol- 
lowing is a list of actions affecting parent windows that can affect child windows: 


Parent Window Child Window 
Shown Shown after the parent window. 
Hidden Hidden prior to the parent window being closed. A 


‘ child window can be visible only when the pent 
window is visible. 


Destroyed Destroyed prior to the parent window being de- 


stroyed. 

Moved Moved with the parent window’s client area. The 
child window is responsible for painting after the 
move. 

Increased in size or Paints any portions of the parent window that have 
maximized been exposed as a result of the increased size of the 


client area. 


Windows does not automatically clip a child window from the parent window’s 
client area. This means the parent window will draw over the child window if it 
carries out any drawing in the same location as the child window. Windows does 
clip the child window from the parent window’s client area if the parent window 
has a WS_CLIPCHILDREN style. If the child window is clipped, the parent 
window cannot draw over it. 


A child window can overlap other child windows in the same client area. Two 
child windows of the same parent window may draw in each other’s client area 
unless one child window has a WS_CLIPSIBLINGS style. Sibling windows are 
child windows that share the same parent window. If the application specifies 
this style for a child window, any portion of that child’s sibling window that lies 
within this window will be clipped. 


If a window has either the WS_CLIPCHILDREN or WS_CLIPSIBLINGS style, 
a slight loss in performance occurs. 


7.2.15 Multiple Document Interface Windows 


Windows multiple document interface (MDI) provides applications with a stand- 
ard interface for displaying multiple documents within the same instance of an 
application. An MDI application creates a frame window which contains a client 
window in place of its client area. An application creates an MDI client window 
by calling CreateWindow with the class MDICLIENT and passing a CLIENT- 
CREATESTRUCT data structure as the function’s [pParam parameter. This 
client window in turn can own multiple child windows, each of which displays a 
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separate document. An MDI application controls these child windows by sending 
messages to its client window. 


For more information on the multiple document interface, see the Guide to 
Programming. 


1.2.16 Title Bar 


The title bar, a rectangle at the top of the window, provides space for the window 
title or name. An application defines the window title when it creates the 
window. It can also change this name anytime by using the SetWindowText 
function. If a window has a title bar, Windows lets the user use the mouse to 
move the window. 


7.2.17 System Menu 


The System menu, identified by an icon at the left end of the title bar, is a pop-up 
menu that contains the system commands. The system commands are commands 
selected by the user to direct Windows to carry out actions on the window, such 
as moving and closing it. 


If a System menu or close box is desired for a window, the WS_SYSMENU and 
WS_CAPTION window styles must be specified when the window is created. 


1.2.18 Scroll Bars 


The horizontal and vertical scroll bars, bars on the right and lower sides of a 
window, let a user scroll the contents of the client area. Windows sends scroll re- 
quests to a window as WM_HSCROLL and WM_VSCROLL messages. If the 
window permits scrolling, the window function must process these messages. 


A window can have one or both scroll bars. To create a window with a scroll bar, 
the application must specify the WS_HSCROLL or WS_VSCROLL window 
style when the window is created. 


1.2.19 Menus 


A menu is a list of commands from which the user can select using the mouse or 
the keyboard. When the user selects an item, Windows sends a corresponding 
message to the window function to indicate which command was selected. 
Windows provides two types of menus: menu bars (sometimes called static 
menus) and pop-up menus. 


A menu bar is a horizontal menu that appears at the top of a window and below 
the title bar, if one exists. Any window except a child window can have a menu 
bar. If an application does not specify a menu when it creates a window; the 
window receives the default menu bar (if any) defined by the window class. 


1-26 Reference — Volume 1 


Pop-up menus contain a vertical list of items and are often displayed when a user 
selects a menu-bar item. In turn, a pop-up menu item can display another pop-up 
menu. Also, a pop-up menu can be “floating.” A floating pop-up menu can ap- 
pear anywhere on the screen designated by the application. An application 
creates an empty pop-up menu by calling the CreatePopupMenu function, and 
then fills in the menu using the AppendMenu and InsertMenu functions. It dis- 
plays the pop-up menu by calling TrackPopupMenu. 


Individual menu: items can be created or modified with the MF_OWNERDRAW 
style, indicating that the item is an owner-draw item. In this case, the owner of — 
the menu is responsible for drawing all visual aspects of the menu item, includ- 
ing checked, grayed, and highlighted states. When the menu is displayed for the 
first time, the window that owns the menu receives a WM_MEASUREITEM 
message. The /Param parameter of this message points to a MEASURE- 
ITEMSTRUCT data structure. The owner then fills in this data structure with 
the dimensions of the item and returns. Windows uses the information in the data 
‘Structure to determine the size of the item so that Windows can appropriately de- 
tect the user’s interaction with the item. 


Windows sends the WM_DRAWITEM message whenever the owner of the 
menu must update the visual appearance of the item. Unlike other owner-draw 
controls, however, the owner of the menu item does not receive the 
WM_DELETEITEM message when the menu item is removed from the menu. A 
top-level menu item cannot be an owner-draw item. 


When the application calls AppendMenu, InsertMenu, or ModifyMenu to add 
an owner-draw menu item to a menu or to change an existing menu item to be an 
owner-draw menu item, the application can supply a 32-bit value as the 
IpNewItem parameter to the function. The application can use this value to main- 
tain additional data associated with the item. This value is available to the appli- 
cation as the itemData field of the structures pointed to by the /Param parameter 
of the WM_MEASUREITEM and WM_DRAWITEM messages. For example, if 
an application were to draw the text in a menu item using a specific color, the 32- 
bit value could contain a pointer to a string. The application could then set the 
text color before drawing the item when it received the WM_DRAWITEM 
message. 


1.2.20 Window State 


The window state can be opened or closed (iconic), hidden or visible, and 
enabled or disabled. The initial state of a window can be set by using the follow- 
ing window styles: 

= WS_DISABLED 

a WS_MINIMIZE 


ep WS_MAXIMIZE 
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m WS_VISIBLE 


Windows creates windows that are initially enabled for input, that is, windows 
that can start receiving input messages immediately. In some cases, an applica- 
tion may need to disable input to a new window. It can disable input by specify- 
ing the WS_DISABLED window style. 


A new window is not displayed until an application opens it by using the Show- 
Window function or specifies the WS_VISIBLE window style when it creates 
the window. For overlapped windows, the WS_ICONIC window style creates a 
window that is minimized initially. 


1.2.21 Life Cycle of a Window 


Because the purpose of any window is to let the user enter data or to let the appli- 
cation display information, a window starts its life cycle when the application has 
a need for input or output. A window continues its life cycle until there is no 
longer a need for it, or the application is terminated. Some windows, such as the 
window used for the application’s main user interface, last the life of the applica- 
tion. Other windows, such as a window used as a dialog box, may last only a few 
seconds. 


The first step in a window’s life cycle is creation. Given a registered window 
class with a corresponding window function, the application uses the CreateWin- 
dow function to create the window. This function directs Windows to prepare in- 
ternal data structures for the window and to return a unique integer value, called 

a window handle, that the application can use to identify the window in sub- 
sequent function calls. 


The first message most windows process is WM_CREATE, the window-creation 
message. Again, the CreateWindow function sends this message to inform the 
window function that it can now perform any initialization, such as allocating 
memory and preparing data files. The wParam parameter is not used, but the 
[Param parameter contains a long pointer to a CREATESTRUCT data struc- 
ture, whose fields correspond to the parameters passed to CreateWindow. 


Both the WM_CREATE and WM_NCCREATE messages are sent directly to the 
window function, bypassing the application queue. This means an application 
will create a window and process the WM_CREATE message before it enters the 
main program loop. 


After a window has been created, it must be opened (displayed) before it can be 
used. An application can open the window in one of two ways: it can specify the 
WS_VISIBLE window style in the CreateWindow function to open the window 
immediately after creation, or it can wait until later and call the ShowWindow 
function to open the window. When creating a main window, an application 
should not specify WS_VISIBLE, but should call ShowWindow from the Win- 
Main function with the nCmdShow parameter set to the desired value. 
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When the window is no longer needed or the application is terminated, the 
window must be destroyed. This is done by using the Destroy Window function. 
Destroy Window removes the window from the system display and invalidates 
the window handle. It also sends WM_DESTROY and WM_NCDESTROY mes- 
sages to the window function. 


The WM_DESTROY message is usually the last message a window function 
processes. This occurs when the Destroy Window function is called or when a 
WM_CLOSE message is processed by the DefWindowProc function. When a 
window function receives a WM_DESTROY message, it should free any allo- 
cated memory and close any open data files. 


The window used as the application’s main user interface should always be the 
last window destroyed and should always cause the application to terminate. 
When this window receives a WM_DESTROY message, it should call the Post- 
QuitMessage function. This function copies a WM_QUIT message to the appli- 
cation’s message queue as a signal for the application to terminate when the 
message is read from the queue. 


7.3 Display and Movement Functions 


Display and movement functions show, hide, move, and obtain information 
. about the number and position of windows on the screen. The following list 
briefly describes each display and movement function: 


Function Description 
ArrangelIconicWindows Arranges minimized (iconic) child windows. 


_ BeginDeferWindowPos _ Initializes memory used by the DeferWindowPos 


function. 

BringWindowToTop Brings a window to the top of a stack of overlapped 
windows. 

CloseWindow Hides the specified window or minimizes it. 

DeferWindowPos Records positioning information for a window to be 
moved or resized by the EndDeferWindowPos 
function. 

EndDeferWindowPos Positions or sizes several windows simultaneously 


based on information recorded by the Defer Win- 
dowPos function. 


GetClientRect Copies the coordinates of a window’s client area. 
GetWindowRect Copies the dimensions of an entire window. 


GetWindowText Copies a window caption into a buffer. 


Window Manager Interface Functions 1-29 


Function 


GetWindowTextLength 
IsIconic 


IsWindowVisible 
IsZoomed 
MoveWindow 
Openlcon 


SetWindowPos 


Set WindowText 
ShowOwnedPopups 
ShowWindow 


7.4 Input Functions 


Description 


Returns the length (in characters) of the given 
window’s caption or text. 


Specifies whether a window is open or closed 
(iconic). 


Determines whether the given window is visible. 
Determines whether a window is maximized. 
Changes the size and position of a window. 
Opens the specified window. 


Changes the size, position, and ordering of child or 
pop-up windows. 


Sets the window caption or text. 
Shows or hides all pop-up windows. 


Displays or removes the given window. 


Input functions disable input from system devices, take control of the system dev- 
ices, or define special actions that Windows takes when an application receives 
input from a system device. (The system devices are the mouse, the keyboard, 
and the timer.) The following list briefly describes each input function: 


Function 


EnableWindow 


GetActiveWindow 
GetCapture 


GetCurrentTime 


GetDoubleClickTime 
GetFocus 


GetTickCount 


Description 


Enables and disables mouse and keyboard input 
throughout the application. 


Returns a handle to the active window. 


Returns a handle to the window with the mouse 
capture. 


Retrieves the current Windows time. 


Retrieves the current double-click time for the 
mouse. 


Retrieves the handle of the window that currently 
owns the input focus. ; 


Returns the number of timer ticks recorded since the 
system was booted. 
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Function 


IsWindowEnabled 


KillTimer 


ReleaseCapture 


SetActiveWindow 
SetCapture 
SetDoubleClickTime 
SetFocus 


SetSysModalWindow 


SetTimer 


SwapMouseButton 


71.5 Hardware Functions 


Description 


Determines whether the specified window is enabled 
for mouse and keyboard input. 


Kills the specified timer event. 


Releases mouse input and restores normal input 
processing. 


Makes a window the active window. 


Causes mouse input to be sent to a specified window. 


Sets the double-click time for the mouse. 
Assigns the input focus to a specified window. 


Makes the specified window a system modal 
window. 


Creates a system-timer event. 


Reverses the meaning of left and right mouse 
buttons. 


Hardware functions alter the state of input devices and obtain state information. 
Windows uses the mouse and the keyboard as input devices. The following list 
briefly describes each hardware function: 


Function 


EnableHardwarelInput 
GetAsyncKeyState 


GetInputState 
GetKBCodePage 
GetKeyboardState 


GetKeyNameText 


GetKeyState 


Description 


Enables or disables mouse and keyboard input 
throughout the application. 


Returns interrupt-level information about the key 
state. 


Returns TRUE if there is mouse or keyboard input. 
Determines which OEM/ANSI tables are loaded. 


Copies an array that contains the state of keyboard 
keys. . 


Retrieves a string containing the name of a key from 
a list maintained by the keyboard driver. 


Retrieves the state of a virtual key. 
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Function Description 


MapVirtualKey Accepts a virtual-key code or scan code for a key 
and returns the corresponding scan code, virtual-key 
code, or ASCH value. 


OemKeyScan Maps OEM ASCII codes 0 through OxOFF into the 
OEM scan codes and shift states. 


SetKeyboardState Sets the state of keyboard keys by altering values in 
an array. 

VkKeyScan Translates an ANSI character to the corresponding 
virtual-key code and shift state for the current 
keyboard. 


7.6 Painting Functions 


Painting functions prepare a window for painting and carry out some useful 
general-purpose graphics operations. Although all the paint functions are specifi- 
cally intended for the system display, some can be used for other output devices. 
The following list briefly describes each painting function: 


Function Description 

BeginPaint Prepares a window for painting. 

DrawFocusRect Draws a rectangle in the style used to indicate focus. 

DrawIcon Draws an icon. 

DrawText Draws characters of a specified string. 

EndPaint Marks the end of window repainting. 

ExcludeUpdateRgn Prevents drawing within invalid areas of a window. 

FillRect Fills a given rectangle by using the specified brush. 

FrameRect . Draws a border for the given rectangle. 

GetDC Retrieves the display context for the client area. 

GetUpdateRect Copies the dimensions of a window region’s bound-’ 
ing rectangle. 

GetUpdateRgn Copies a window’s update region. 

GetWindowDC Retrieves the display context for an entire window. 

GrayString Writes the characters of a string using gray text. 


InvalidateRect Marks a rectangle for repainting. 
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Function Description 

InvalidateRgn Marks a region for repainting. 

InvertRect Inverts the display bits of the specified rectangle. 

ReleaseDC Releases a display context. 

Update Window Notifies the application when parts of a window 
need redrawing. 

ValidateRect Releases the specified rectangle from repainting. 

ValidateRgn Releases the specified region from repainting. 


1.6.1 How Windows Manages the Display 


The system display is the principal display device for all applications running 
with Windows. All applications are free to display some form of output on the 
system display, but since many applications can run at one time, applications are 
not entitled to the entire system display. The complete system display must be 
shared. Windows shares the system display by carefully managing the access that 
applications have to it. Windows ensures that applications have space to display 
output but do not draw in the space reserved for other applications. 


Windows manages the system display by using the display context type. The dis- 
play context is a special device context that treats each window as a separate dis- 
play surface. An application that retrieves a display context for a specific 
window has complete control of the system display within that window, but can- 
not access or paint over any part of the display outside the window. With a dis- 
play context, an application can use GDI painting functions, as well as the output 
functions described in this section, to draw in the given window. 


1.6.2 Display Context Types 


There are four types of display contexts: common, class, private, and window. 
The common, class, and private display contexts permit drawing in the client 
area of a given window. The window display context permits drawing anywhere 
in the window. When a window is created, Windows assigns a common, class, or 
private display context to it, based on the type of display context specified in that 
window’s class style. 


Common Display Context 


A common display context is the default context for all windows. Windows as- 
signs a common display context to the window if a display-context type is not 
explicitly specified in the window’s class style. 
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A common display context permits drawing in a window’s client area, but it is 
not immediately available for use by a window. A common display context must 
be retrieved from a cache of display contexts before a window can carry out any 
drawing in its client area. The GetDC or BeginPaint function retrieves the dis- 
play context and returns a handle to the context. The handle can be used with 
GDI functions to draw in the client area of the given window. After drawing is 
complete, the context must be returned to the cache by using the ReleaseDC or 
EndPaint function. After the context is released, drawing cannot occur until 
another display context is retrieved. 


When a common display context is retrieved, Windows gives it default selections 
for pen, brush, font, clipping area, and other attributes. These attributes define the 
tools currently available to carry out the actual drawing. Table 1.4 lists the de- 
fault selections for a common display context: 


Table 1.4 Defaults for a Display Context 

Attribute Default 

Background color White 

Background mode OPAQUE 

Bitmap No default. 

Brush WHITE_BRUSH 

Brush origin (0,0) 

Clipping region Entire client area with the update region clipped as ap- 
propriate. Child and pop-up windows in the client area 
may also be clipped. 

Color palette DEFAULT_PALETTE 


Current pen position 
Device origin 
Drawing mode 


Font 


Intercharacter spacing 
Mapping mode 

Pen 

Polygon-filling mode 
Relative-absolute flag 
Stretching mode 

Text color 

Viewport extent 


Viewport origin 


(0,0) 
Upper-left corner of client area. 
R2_COPYPEN 


SYSTEM_FONT (SYSTEM_FIXED_FONT for appli- 
cations written to run with Windows versions prior to 
3.0) 


0 

MM_TEXT 
BLACK_PEN 
ALTERNATE 
ABSOLUTE 
BLACKONWHITE 
Black 

(1,1) 

(0,0) 
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Table 1.4 Defaults for a Display Context (continued) 


Attribute Default 
Window extents (1,1) 
Window origin (0,0) 


An application can modify the attributes of the display context by using the selec- 
tion functions and display-context attribute functions. For example, applications 
typically change the selected pen, brush, and font. 


When a common display context is released, the current selections, such as map- 
ping mode and clipping area, are lost. Windows does not preserve the previous 
selections of a common display context since these contexts are shared and 
Windows has no way to guarantee that the next window to use a given common 
display context will be the last window to use that context. Applications that 
modify the attributes of a common display context must do so each time another 
context is retrieved. 


Class Display Context 


A window has a class display context if the window class specifies the 
CS_CLASSDC style. A class display context is shared by all windows in a given 
class. A class display context is not part of the display context cache. Instead, 
Windows specifically allocates a class context for sole use by the window class. 


A class display context must be retrieved before it can be used, but it does not 
have to be released after use. As long as only one window from the class uses the 
context, the class display context can be kept and reused. If another window in 
the class needs to use the context, that window must retrieve it before any draw- 
ing occurs. Retrieving the context sets the correct origin and clipping for the new 
window and ensures that the context will be applied to the correct window. A 
handle to the class display context can be retrieved by using the GetDC or Begin- 
Paint function. The ReleaseDC and EndPaint functions have no effect on the 
class display context. 


A class display context is given the same default selections as a common display 

‘context when the first window of the class is created (see Table 1.4, “Defaults for 
a Display Context”). These selections can be modified at any time. Windows pre- 
serves all new selections made for the class display context, except for the clip- 
ping region and device origin, which are adjusted for the current window when 
the context is retrieved. Otherwise, all other attributes remain unchanged. This 
means a change made by one window applies to all windows that subsequently 
use the context. 
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NOTE Changing the mapping mode of a class display context may have an undesirable ef- 
fect on how a window’s background is erased. For more information, see Section 1.6.7, 
“Window Background,” and Section 2.5, “Mapping Functions.” 


Private Display Context 


A window has a private display context if the window class specifies the 
CS_OWNDC style. A private display context is used exclusively by a given 
window. A private display context is not part of the display context cache. In- 
stead, Windows specifically allocates the context for sole use by the window. 


A private display context needs to be retrieved only once. Thereafter, it can be 
kept and used any number of times by the window. Windows automatically up- 
dates the context to reflect changes to the window, such as moving or sizing. A 
handle to a private display context can be retrieved by using the GetDC or Begin- 
Paint function. The ReleaseDC and EndPaint functions have no effect on the 
private display context. 


A private display context is given the same default selections as a common dis- 
play context when the window is created (see Table 1.4, “Defaults for a Display 
Context”). These selections can be modified at any time. Windows preserves any 
~ new selections made for the context. New selections, such as clipping region and 
brush, remain selected until the window specifically makes a change. 


NOTE Changing the mapping mode of a private display context may have an undesirable 
effect on how the window’s background is erased. For more information, see Section 1.6.7, 
“Window Background,” and Section 2.5, “Mapping Functions.” 


Window Display Context 


A window display context permits painting anywhere in a window, including the 
caption bar, menus, and scroll bars. Its origin is the upper-left corner of the 
window, instead of the upper-left corner of the client area. 


The GetWindowDC function retrieves a window display context from the same 
cache as it does common display contexts. Therefore, a window that uses a 
window display context must release it with the ReleaseDC function immedi- 
ately after drawing. 


Windows always sets the current selections of a window display context to the 
same default selections as a common display context and does not preserve any 
change the window may have made to these selections (see Table 1.4, “Defaults 
for a Display Context”). Windows does not allow private or class window dis- 
play contexts, so CS_OWNDC and CS_CLASSDC class styles have no effect on 
the window display context. 


A window display context is intended to be used for special painting within a 
window’s nonclient area. Since painting in nonclient areas of overlapped 
windows is not recommended, most applications reserve a display context for 
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designing custom child windows. For example, an application may use the dis- 
play context to draw a custom border around the window. In such cases, the 
window usually processes the WM_NCPAINT message instead of passing it on 
to the DefWindowProc function. For applications that do not process 
WM_NCPAINT messages but still wish to paint in the nonclient area, the 
GetSystemMetrics function can be used to retrieve the dimensions of various 
parts of the nonclient area, such as the caption bar, menu bar, and scroll bars. 


1.6.3 Display-Context Cache 


Windows maintains a cache of display contexts that it uses for common and 
window display contexts. This cache contains five display contexts, which means 
only five common display contexts can be active at any one time. To prevent 
more than five from being retrieved, a window that uses a common or window 
display context must release that context immediately after drawing. 


If a window fails to release a common display context, all five display contexts 
may eventually be active and unavailable for any other window. In such a case, 
Windows ignores all subsequent requests for a common display context. In the re- 
tail version of Windows, the system will appear to be deadlocked, while the de- 
bugging version of Windows will undergo a fatal exit, alerting the developer of a 
problem. 


The ReleaseDC function releases a display context and returns it to the cache. 
Class and private display contexts are individually allocated for each class or 
window; they do not belong to the cache so they do not need to be released after 
use. 


1.6.4 Painting Sequence 


Windows carries out many operations to manage the system display that affect 
the content of the client area. If Windows moves, sizes, or alters the appearance 
of the display, the change may affect a given window. If so, Windows marks the 
area changed by the operation as ready for updating and, at the next opportunity, 
sends a WM_PAINT message to the window so that it can update the window in 
the update region. If a window paints in its client area, it must call the Begin- 
Paint function to retrieve a handle to a display context, must update the changed 
area as defined by the update region, and finally, must call the EndPaint func- 
tion to complete the operation. 


A window is free to paint in its client area at any time, that is, at times other than 
in response to a WM_PAINT message. The only requirement is that it retrieve a 
display context for the client area before carrying out any operations. 
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7.6.5 WM_PAINT Message 


The WM_PAINT message is a request from Windows to a given window to up- 
date its display. Windows sends a WM_PAINT message to a window whenever 
it is necessary to repaint a portion of an application’s window. When a window 
receives a WM_PAINT message, it should retrieve the update region by using 
the BeginPaint function, and it should carry out whatever operations are neces- 
sary to update that part of the client area. 


The InvalidateRect and InvalidateRgn functions do not actually generate 
WM_PAINT messages. Instead, Windows accumulates the changes made by 
these functions and its own changes while a window processes other messages in 
its application queue. Postponing the WM_PAINT message lets a window 
process all changes at once instead of updating bits and pieces in time-consuming 
individual steps. 


A window can require Windows to send a WM_PAINT message by using the 
UpdateWindow function. The Update Window function sends the message 
directly to the window, regardless of the number of other messages in the applica- 
tion queue. UpdateWindow is typically used when a window wants to update its 
client area immediately, such as just after the window is created. 


Once a window receives a WM_PAINT message, it must call the BeginPaint 
function to retrieve the display context for the client area and to retrieve other 
information such as the update region and whether the background has been 
erased. 


Windows automatically selects the update region as the clipping region of the dis- 
play context. Since GDI discards (clips) drawing that extends outside the clip- 
ping region, only drawing that is in the update region is actually visible. For 

more information about the clipping region, see Section 2.8, “Clipping Func- 
tions.” 


The BeginPaint function empties the update region to prevent the same region 
from generating subsequent WM_PAINT messages. 


After completing the painting operation, the window must call the EndPaint 
function to release the display context. 


7.6.6 Update Region 


An update region defines the part of the client area that is marked for painting on 
the next WM_PAINT message. The purpose of the update region is to save some 
applications the time it takes to paint the entire contents of the client area. If only 
the part that needs painting is added to the update region, only that part is 
painted. For example, if a word changes in the client area of a word-processing 
application, only the word needs to be painted, not the entire line of text. This 
saves the time it takes the application to draw the text, especially if there are 
many different sizes and typefaces. 
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The InvalidateRect and InvalidateRgn functions add a given rectangle or re- 
gion to the update region. The rectangle or region must be given in client coordi- 
nates. The update region itself is defined in client coordinates. Windows adds its 
own rectangles and regions to a window’s update region after operations such as 
moving, sizing, and scrolling the window. 


The ValidateRect and ValidateRgn functions remove a given rectangle or re- 
gion from the update region. These functions are typically used when the 
window has updated a specific part of the display in the update region before re- 
ceiving the WM_PAINT message. 


The GetUpdateRect and GetUpdateRgn functions retrieve the smallest 
rectangle that encloses the entire update region. These functions can be used to 
compute the current size of the update region to determine if painting is required. 


1.6.7 Window Background 


The window background is the color or pattern the client area is filled with 
before a window begins painting in the client area. Windows paints the back- 
ground for a window or gives the window the opportunity to do so by sending a 
WM_ERASEBKGND message to the window when the application calls the 
BeginPaint function. 


The background is important since if not erased, the client area will contain 
whatever was originally on the system display before the window was moved 
there. Windows erases the background by filling it with the background brush 
specified by the window’s class. 


Windows applications that use class or private display contexts should be careful 
about erasing the background. Windows assumes the background is to be com- 
puted by using the MM_TEXT mapping mode. If the display context has any 
other mapping mode, the area erased may not be within the visible part of the 
client area. 


7.6.8 Brush Alignment 


Brush alignment is particularly important on the system display where scrolling 
and moving are commonplace. A brush is a pattern of bits with a minimum size 
of 8-by-8 bits. GDI paints with a brush by repeating the pattern again and again 
within a given rectangle or region. If the region is moved by an arbitrary 
amount—for example, if the window is scrolled—and the brush is used again to 
filled empty areas around the original area, there is no guarantee that the original 
pattern and the new pattern will be aligned. For example, if the scroll moves the 
original filled area up one pixel, the intersection of the original area and any new 
painting will be out of alignment by one pixel, or bit. Depending on the pattern, 
this may have a undesirable visual effect. 
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To ensure that a brush is aligned after a window is moved, an application must 
take the following steps: 


1. Call the SelectObject function to select a different brush. 
2. Call the SetBrushOrg function to realign the current brush. 


3. Call the UnrealizeObject function to realign the origin of the original brush 
when it is selected next. 


4. Call the SelectObject function to select the original brush. 


1.6.9 Painting Rectangular Areas 


The FillRect, FrameRect, and InvertRect functions provide an easy way to 
Carry out painting operations on rectangles in the client area. 


The FillRect function fills a rectangle with the color and pattern of a given 
~ brush. This function fills all parts of the rectangle, including the edges or borders. 


The FrameRect function uses a brush to draw a border around a rectangle. The 
border width and height is one unit. 


The InvertRect function inverts the contents of the given rectangle. On mono- 
chrome displays, white pixels become black, and vice versa. On color displays, 
the results depend on the method used by the display to generate color. In either 
case, calling InvertRect twice with the same rectangle restores the display to its 
original colors. 


7.6.10 Drawing Icons 


The DrawlIcon function draws an icon at a given location in the client area. An 
icon is a bitmap that a window uses as a symbol to represent an item or concept, 
such as an application or a warning. 


An icon can be created by using the SDKPaint program, added to an applica- 
tion’s resources by using the Resource Compiler, and loaded into memory by 
using the LoadIcon function. Applications can also call the CreateIcon function 
to create an icon and can modify a previously loaded or created icon at any time. 
An icon resource is in global memory and its handle is the handle to that 
memory. An application can free memory used to store an icon created by 
CreatelIcon by calling DeleteIcon. 


1.6.11 Drawing Formatted Text 


The DrawText function formats and draws text within a given rectangle in the 
client area. This function provides simple text processing that most applications, 
other than word processors, can use to display text. DrawText output is similar 


1-40 Reference — Volume 1 


to the output generated by a terminal, except it uses the selected font and can clip 
the text if it extends outside a given rectangle. DrawText provides many differ- 
ent formatting styles. Table 1.5 lists the styles that are available: 


Table1.5 Text Formatting Styles 


Value Description 

DT_BOTTOM Bottom-justified (single line only). 
DT_CENTER Centered. 

DT_EXPANDTABS Expands tab characters into spaces. Otherwise, 


tabs are treated as single characters. The number 
of spaces depends on the tab stop size specified 
by DT_TABSTOP. If DT_TABSTOP is not given, 
the default is eight spaces. 


DT_EXTERNALLEADING Includes the font external leading in line height. 
External leading is not included in the height of a 
line of text. (Leading is the space between lines of 
text.) If DT_EXTERNALLEADING is not 
given, there is no spacing between lines of text. 
Depending on the selected font, this means that 
characters in different lines may touch or overlap. 


DT_LEFT Left-justified. Default. 


DT_NOCLIP Draws text without clipping. All text.will be 
drawn even if it extends outside the specified 
rectangle. The DrawText function is somewhat 
faster when DT_NOCLIP is used. 


DT_RIGHT Right-justified. 

DT_SINGLELINE Single line only. Carriage returns and linefeeds do 
not break the line. Default is multiple-line format- 
ting. 

DT_TABSTOP Sets tab stops. The high-order byte of the wFor- 


mat parameter is the number of characters for 
each tab. If DT_TABSTOP is not given, the de- 
fault tab size is eight spaces. 


DT_TOP Top-justified (single line only). Default. 
DT_VCENTER Vertically centered (single line only). 
DT_WORDBREAK Sets word breaks. Lines are automatically broken 


between words if a word would extend past the 
edge of the rectangle specified by the /pRect para- 
meter. Carriage-return/linefeed sequence also 
causes a line break. Word-break characters are 
space, tab, carriage return, linefeed, and carriage- 
return/linefeed combinations. Applies to 
multiple-line formatting only. 
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The DrawText function uses the selected font, so applications can draw for- 
matted text in other than the system font. 


DrawText does not hyphenate, and although it can justify text to the left, right, 
or center, it cannot combine justification styles. In other words, it cannot justify 
both left and right. 


DrawText recognizes a number of control characters and carries out special ac- 
tions when it encounters them. Table 1.6 lists the control characters and the re- 
spective action: 


Table 1.6 DrawText Control Characters 
Character (ANSI value) Action 


Carriage return(13) Interpreted as a line-break character. The text is 
immediately broken and started on the next line 
down in the rectangle. 


Linefeed(10) Interpreted as a line-break character. The text is 
immediately broken and started on the next line 
down in the rectangle. 


A carriage-return/linefeed character combination 
is interpreted as a single line-break character. 

Space(32) Interpreted as a word-break character if the 
DT_WORDBREAK style is given. If the text is 
too long to fit on the current line in the formatting 
rectangle, the line is broken at the closest word- 
break character to the end of the line. 


Tab(9) Expanded into a given number of spaces if the 
DT_EXPANDTABS style is given. The number 
of spaces depends on what tab-stop value is given 
with the DT_TABSTOP style. The default is eight. 


1.6.12 Drawing Gray Text 


An application can draw gray text by calling the SetTextColor function to set 
the current text color to the COLOR_GRAYTEXT, the solid gray system color 
used to draw disabled text. However, if the curent display driver does not support 
a solid gray color, this value is set to zero. 


The GrayString function is a multiple-purpose function that gives applications 
another way to gray text or carry out other customized operations on text or bit- 
maps before drawing the result in a client area. To gray text, the function creates 
a memory bitmap, draws the string in the bitmap, and then grays the string by 
combining it with a gray brush. The GrayString function finally copies the gray 
text to the display. An application can intercept or modify each step of this 
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process, however, to carry out custom effects, such as changing the gray brush to 
a patterned brush or drawing an icon instead of a string. 


If GrayString is used to draw gray text only, GrayString uses the selected font 
of the given display context. GrayString sets text color to black. It creates a bit- 
map, and then uses the TextOut function to write a given string to the bitmap. It 
then uses the PatBIt function and a gray brush to gray the text, and uses the 
BitBlt function to copy the bitmap to the client area. 


GrayString assumes that the display context for the client area has MM_TEXT 
mapping mode. Other mapping modes cause undesirable results. 


GrayString lets an application modify this graying procedure in three ways: by 
defining an additional brush to be combined with the text before being displayed, 
by replacing the call to the TextOut function with a call to an application-sup- 
plied function, and by disabling the call to the PatBIt function. 


The additional brush is defined as a parameter. This brush is combined with the 
text as the text is being copied to the client area by the BitBlt function. The addi- 
tional brush is intended to be used to give the text a desired color, since the bit- 
map used to draw the text is a monochrome bitmap. 


The application-supplied function is also defined as a parameter. If a non-NULL 
value is given for the function, GrayString automatically calls the application- 
supplied function instead of the TextOut function and passes it a handle to the 
display context for the memory bitmap as well as the long pointer and count 
passed to GrayString. The function can carry out any operation and interpret the 
long pointer and count in any way. For example, a negative count could be used 
to indicate that the long pointer points to an icon handle that signals the applica- 
tion-supplied function to draw the icon and let GrayString gray and display it. 
No matter what type of drawing the function carries out, GrayString assumes it 
is successful if the application-supplied function returns TRUE. 


GrayString suppresses graying if it receives an ncount parameter equal to —1 
and the application-supplied function returns FALSE. This is a way to combine 
custom patterns with the text without interference from the gray brush. 


7.6.13 Nonclient-Area Painting 


Windows sends a WM_NCPAINT message to the window whenever the non- 
client area of the window, such as the title bar, menu bar, and window frame, 
needs painting. Processing this message is not recommended since a window that 
does so must be able to paint all the required parts of the nonclient area for the 
window. In other words, a window should pass this message on to the DefWin- 
dowProc function for default processing unless the Windows application is creat- 
ing a custom nonclient area for a child window. 


1.7 Dialog-Box Functions 
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Dialog-box functions create, alter, test, and destroy dialog boxes and controls 
within dialog boxes. A dialog box is a temporary window that Windows creates 
for special-purpose input, and then destroys immediately after use. An applica- 
tion typically uses a dialog box to prompt the user for additional information 
about a current command selection. The following list briefly describes each 


dialog function: 


Function 


CheckDlgButton 
CheckRadioButton 


CreateDialog 
CreateDialogIndirect 


CreateDialogIndirectParam 


CreateDialogParam 


DefDlgProc 


DialogBox 
DialogBoxIndirect 


DialogBoxIndirectParam 


DialogBoxParam 
DigDirList 


DigDirListComboBox 


Description 


Places/removes a check, or changes 
the state of the three-state button. 


Checks a specified button and re- 
moves checks from all others. 


Creates a modeless dialog box. 


Creates a modeless dialog box from a 
template. 


Creates a modeless dialog box from a 
template and passes data to it when it 
is created. 


Creates a modeless dialog box and 
passes data to it when it is created. 


Provides default processing for any 
Windows messages that a dialog box 
with a private window class does not 
process. 


Creates a modal dialog box. 


Creates a modal dialog box from a 
template. 


Creates a modal dialog box from a 
template and passes data to it when it 
is created. 


Creates a modal dialog box and 
passes data to it when it is created. 


Fills the list box with names of files 
matching a path. 


Fills a combo box with names of files 
matching a path. 
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Function 


DigDirSelect 
DigDirSelectComboBox 


EndDialog 


GetDialogBaseUnits 


GetDlgCtrlID 
GetDlgItem 
GetDlgItemInt 
GetDlgItemText 
GetNextDlgGroupItem 
GetNextDlgTabItem 
IsDialogMessage 


IsDlgButtonChecked 
MapDialogRect 


SendDlgItemMessage 
SetDlgItemInt 


SetDlgItemText 


Description 


Copies the current selection from a 
list box to a string. 


Copies the current selection from a 
combo box to a string. 


Frees resources and destroys 
windows associated with a modal 
dialog box. 


Retrieves the base dialog units used 
by Windows when creating a dialog 
box. ; 


Returns the ID value of a control 
window. 


Retrieves the handle of a dialog item 
from the given dialog box. 


Translates the control text of an item 
into an integer value. 


Copies an item’s control text into a 
string. 


Returns the window handle of the 
next item in a group. 


Returns the window handle of the 
next or previous item. 


Determines whether a message is in- 
tended for the given dialog box. 


Tests whether a button is checked. 


Converts the dialog-box coordinates 
to client coordinates. 


Sends a message to an item within a 
dialog box. 


Sets the caption or text of an item to 
a String that represents an integer. 


Sets the caption or text of an item to 
a string. 
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1.7.1 Uses for Dialog Boxes 


For convenience and to keep from introducing device-dependent values into the 
application code, applications use dialog boxes instead of creating their own 
windows. This device independence is maintained by using logical coordinates in 
the dialog-box template. Dialog boxes are convenient to use because all aspects 
of the dialog box, except how to carry out its tasks, are predefined. Dialog boxes 
supply a window class and procedure, and create the window for the dialog box 
automatically. The application supplies a dialog function to carry out tasks and a 
dialog-box template that describes the dialog style and content. 


Modeless Dialog Box 


A modeless dialog box allows the user to'supply information to the dialog box 
and return to the previous task without canceling or removing the dialog box. 
Modeless dialog boxes are typically used as a way to let the user continually 
supply information about the current task without having to select a command 
from a menu each time. For example, modeless dialog boxes are often used with 
a text-search command in word-processing applications. The dialog box remains 
displayed while the search is carried out. The user can then return to the dialog 
box and search for the same word again, or change the entry in the dialog box 
and search for a new word. 


An application with a modeless dialog box processes messages for that box by 
using the IsDialogMessage function inside the main message loop. The dialog 
function of a modeless dialog box must send a message to the parent window 
when it has input for the parent window. It must also destroy the dialog box 
when it is no longer needed. A modeless dialog box can be destroyed by using 
the Destroy Window function. An application must not call the EndDialog func- 
tion to destroy a modeless dialog box. 


Modal Dialog Box 


A modal dialog box requires the user to respond to a request before the applica- 
tion continues. Typically, a modal dialog box is used when a chosen command 

needs additional information before it can proceed. The user should not be able 
to continue some other operation unless the command is canceled or additional 

information is provided. . 


A modal dialog box disables its parent window, and it creates its own message 
loop, temporarily taking control of the application queue from the main loop of 
the program. A modal dialog box is displayed when the application calls the 
DialogBox function. 


By default, a modal dialog box cannot be moved by the user. An application can 
create a moveable dialog box by specifying the WS_CAPTION and, optionally, 
the WS_SYSMENU window styles. 
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The dialog box is displayed until the dialog function calls the EndDialog func- 
tion, or until Windows is terminated. The parent window remains disabled unless 
the dialog box enables it. Note that enabling the parent window is not recom- 
mended since it defeats the purpose of the modal dialog box. 


System-Modal Dialog Box 


A system-modal dialog box is identical to a modal dialog box except that all 
windows, not just the parent window, are disabled. System-modal dialog boxes 
must be used with care since they effectively shut down the system until the user 
supplies the required information. 


1.7.2 Creating a Dialog Box 


A dialog box is created by using either the CreateDialog or DialogBox function. 
These functions load a dialog-box template from the application’s executable 
file, and then create a pop-up window that matches the template’s specifications. 
The dialog box belongs to the predefined dialog-box class unless another class is 
explicitly defined. The DialogBox function creates a modal dialog box; the 
CreateDialog function creates a modeless dialog box. 


Use the WS_ VISIBLE style for the dialog-box template if you want the dialog 
box to appear upon creation. 


Dialog-Box Template 


The dialog-box template is a description of the dialog box: its height and width, 
the controls it contains, its style, the type of border it uses, and so on. A template 
is an application’s resource and must be added to the application’s executable file 
by using the Resource Compiler. 


Dialog boxes can be easily modified and are system independent, enabling an 
application developer to change the template without changing the source code. 


The CreateDialog and DialogBox functions load the resource into memory 
when they create the dialog box, and then use the information in the dialog tem- 
plate to create the dialog box, position it, and create and position the controls for 
the dialog box. 


The Resource Compiler takes a text description of the template and converts it to 
the required binary form. This binary form is added to the application’s exe- 
cutable file. 


Dialog-Box Measurements 


Dialog box and control dimensions and coordinates are device independent. 
Since a dialog box may be displayed on system displays that have widely varying 
pixel resolutions, dialog-box dimensions are specified in system character widths 
and heights instead of pixels. Characters are guaranteed to give the best possible 
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appearance for a given display. One unit in the x direction is equal to 4 of the 
dialog base width unit. One unit in the y direction is equal to 1 of the dialog 
base height unit. The dialog base units are computed from the height and width 
of the system font; the GetDialogBaseUnits function returns the dialog base 
units for the current display. Applications can convert these measurements to pix- 
els by using the MapDialogRect function. 


Windows does not allow the height of a dialog box to exceed the height of a full- 
screen window. The width of a dialog box is not allowed to be greater than the 
width of the screen. 


1.7.3 Return Values from a Dialog Box 


The DialogBox function that creates a modal dialog box does not return until the 
dialog function has called the EndDialog function to signal the end of the dialog 
box. When control finally returns from the DialogBox function, the return value 
is equal to the value specified in the EndDialog function. This means a modal 
dialog box can return a value through the EndDialog function. 


Modeless dialog boxes cannot return values in this way since they do not use the 
EndDialog function to terminate execution and do not return control in the same 
way a modal dialog box does. Instead, modeless dialog boxes return values to 
their parent windows by using the SendMessage function to send a notification 
message to the parent window. Although Windows does not explicitly define the 
content of a notification message, most applications use a WM_COMMAND 
message with an integer value that identifies the dialog box in the wParam para- 
meter and the return value in the /Param parameter. Modal dialog boxes may 
also use this technique to return values to their parent windows before terminat- 


ing. 


1.7.4 Controls in a Dialog Box 


A dialog box can contain any number and any type of controls. A control is a 
child window that belongs to a predefined or application-defined window class 
and that gives the user a method of supplying input to the application. Examples 
of controls are push buttons and edit controls. Most dialog boxes contain one or 
more controls of the predefined class. The number of controls, the order in which 
they should be created, and the location of each in the dialog box are defined by 
the control statements given in the dialog-box template. 


Control Identifiers 


Every control in a dialog box needs a unique control identifier, or ID, to distin- 
guish it from other controls. Since all controls send information to the dialog 
function through WM_COMMAND messages, the control identifiers are essen- 
tial for the dialog box to determine which control sent a given message. 
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All identifiers for all controls in the dialog box must be unique. If a dialog box 

has a menu bar, there must be no conflict between menu-item identifiers and con- 
trol identifiers. Since Windows sends menu input to a dialog function as 
WM_COMMAND messages, conflicts with menu and control identifiers can 
cause errors. Menus in dialog boxes are not recommended. 


The dialog function usually identifies the dialog-box controls by using their con- 
trol identifier. Occasionally the dialog function requires the window handle that 
was given to the control when it was created. The dialog function can retrieve 
this window handle by using the GetDlgItem function. 


General Control Styles 


The WS_TABSTOP style specifies that the user can move the input focus to the 
given control by pressing the TAB or SHIFT+TAB keys. Typically, every control in 
the dialog box has this style, so the user can move the input focus from one con- 
trol to the other. If two or more controls are in the dialog box, the TAB key moves 
the input focus to the controls in the order in which they have been created. The 
SHIFT+TAB keys move the input focus in reverse order. For modal dialog boxes, 
the TAB and SHIFT+TAB keys are automatically enabled for moving the input . 
focus. For modeless dialog boxes, the IsDialogMessage function must be used to 
filter messages for the dialog box and to process these key strokes. Otherwise, 

the keys have no special meaning and the WS_TABSTOP style is ignored. 


The WS_GROUP style specifies that the user can move the input focus to the 
given control by using a DIRECTION key. Typically, the first and last controls in a 
group of consecutive controls in the dialog box have this style, so the user can 
move the input focus from one control to the other. The DOWN and RIGHT keys 
move the input focus to controls in the order in which they have been created. 
The UP and LEFT keys move the input focus in reverse order. For modal dialog 
boxes, the DIRECTION keys are automatically enabled for moving the input focus. 
For modeless dialog boxes, the IsDialogMessage function must be used to filter 
messages for the dialog box and to process these key strokes. Otherwise, the keys 
have no special meaning and the WS_GROUP style is ignored. 


Buttons 


Button controls are the principal interface of a dialog box. Almost all dialog 
boxes have at least one push-button control and most have one default push but- 
ton and one or more other push buttons. Many dialog boxes have collections of 
radio buttons enclosed in group boxes, or lists of check boxes. 


Most modal or modeless dialog boxes that use the special keyboard interface 
have a default push button whose control identifier is set to 1 so that the action 
the dialog function takes when the button is clicked is identical to the action 
taken when the ENTER key is pressed. There can be only one button with the de- 
fault styie; however, an application can assign the default style to any button at 
any time. These dialog boxes may also set the control identifier of another push 
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button to 2 so that the action of the ESCAPE key is duplicated by clicking that 
button. 


When a dialog box first starts, the dialog function can set the initial state of the 
button controls by using the CheckDlgButton function, which sets or clears the 
button state. This function is most useful when used to set the state of radio but- 
tons or check boxes. If the dialog box contains a group of radio buttons in which 
only one button should be set at any given time, the dialog function can use the 
CheckRadioButton function to set the button and automatically clear any other 
radio button. 


Before a dialog box terminates, the dialog function can check the state of each 
button control by using the IsDlgButtonChecked function, which returns the cur- 
rent state of the button. A dialog box typically saves this information to initialize 
the buttons the next time the dialog box is created. 


Edit Controls 


Many dialog boxes have edit controls that let the user supply text as input. Most 
dialog functions initialize an edit control when the dialog box first starts. For ex- 
ample, the function may place a proposed filename in the control that the user 
can adapt or modify. The dialog function can set the text in an edit control by 
using the SetDlgItemText function, which copies text in a given buffer to the 
edit control. When the edit control receives the input focus, the complete text 
will automatically be selected for editing. 


Since edit controls do not automatically return their text to the dialog box, the 
dialog function must retrieve the text before terminating. It can retrieve the text 
by using the GetDlgItemText function, which copies the edit-control text to a 
buffer. The dialog function typically saves this text to initialize the edit control 
later, or passes it on to the parent window for processing. 


Some dialog boxes use edit controls that let the user enter numbers. The dialog 
function can retrieve a number from an edit control by using the GetDlgItemInt 
function, which retrieves the text of the control and converts the text to a decimal 
value. The user enters the number in decimal digits. It can be either signed or un- 
signed. The dialog function can display an integer by using the SetDigItemInt 
function. It converts a signed or unsigned integer to a string of decimal digits. 


List Boxes and Directory Listings 


Some dialog boxes display lists, such as filenames, from which the user can 
select one or more names. Dialog boxes that display a list typically use list-box 
controls. Dialog boxes that display a list of filenames typically use a list-box 
control and the DigDirList and DigDirSelect functions. The DlgDirList func- 
tion automatically fills a list box with the filenames in the current directory. The 
DlgDirSelect function retrieves the selected filename from the list box. Together 
they provide a convenient way for a dialog box to display a directory listing, and 
let the user select a file without having to type in the name of the directory and 
file. 
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Combo Boxes 


Another method for providing a list of items to a user is by means of a combo 
box. A combo box consists of either a static text field or edit field combined with 
a list box. The list box can be displayed at all times or pulled down by the user. If 
the combo box contains a static text field, the text field always displays the cur- 
rent selection (if any) in the list-box portion of the combo box. If it uses an edit 
field, the user can type in the desired selection; the list box highlights the first 
item (if any) which matches what the user has entered in the edit field. The user 
can then select the item highlighted in the list box to complete the choice. 


Owner-Draw Dialog-Box Controls 


List boxes, combo boxes, and buttons can be designated as owner-draw controls 
by creating them with the appropriate style: 


Style Meaning 


LBS_OWNERDRAWFIXED Creates an owner-draw list box with 
items that have the same, fixed height. 


LBS_OWNERDRAWVARIABLE Creates an owner-draw list box with 
items that have different heights. 


CBS_OWNERDRAWFIXED Creates an owner-draw combo box 
with items that have the same, fixed 
height. 


CBS_-OWNERDRAWVARIABLE Creates an owner-draw combo box 
with items that have different heights. 


BS_OWNERDRAW Creates an owner-draw button. 


When a control has the owner-draw style, Windows handles the user’s interac- 
tion with the control as usual, such as detecting when a user has clicked a button 
and notifying the button’s owner of the event. However, because it is an owner- 
draw control, the owner of the control is completely responsible for the visual ap- 
pearance of the control. 


When Windows first creates a dialog box containing owner-draw controls, it 
sends the owner a WM_MEASUREITEM message for each owner-draw control. 
The /Param parameter of this message contains a pointer to a MEASURE- 
ITEMSTRUCT data structure. When the owner receives the message for a con- 
trol, the owner fills in the appropriate fields of the structure and returns. This 
informs Windows of the dimensions of the control or of its items so that 
Windows can appropriately detect the user’s interaction with the control. If a list 
box or combo box is created with the LBS_OWNERDRAWVARIABLE or 
CBS_OWNERDRAWVARIABLE style, this message is sent to the owner for 
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each item in the control, since each item can differ in height. Otherwise, this 
message is sent once for the entire owner-draw control. 


Whenever an owner-draw control needs to be redrawn, Windows sends the 
WM_DRAWITEM message to the owner of the control. The /Param parameter 
of this message contains a pointer to a DRAWITEMSTRUCT data structure 
that contains information about the drawing required for the control. Similarly, if 
an item is deleted from a list box or combo box, Windows sends the 
WM_DELETEITEM message containing a pointer to a DELETEITEM- 
STRUCT data structure that describes the deleted item. 


Messages for Dialog-Box Controls 


Many controls recognize predefined messages that, when sent to the control, 

cause it to carry out some action. A dialog function can send a message to acon- _ 
trol by supplying the control identifier and using the SendDlgItemMessage func- 
tion, which is identical to the SendMessage function except that it uses a control 
identifier instead of a window handle to identify the control that is to receive the 
message. 


1.7.5 Dialog-Box Keyboard Interface 


Windows provides a special keyboard interface for modal dialog boxes and 
modeless dialog boxes that use the IsDialogMessage function to filter messages. 
This keyboard interface carries out special processing for several keys and gener- 
ates messages that correspond to certain buttons in the dialog box or changes the 
input focus from one control to another. Table 1.7 lists the keys used in this inter- 
face and the respective action: 


Table1.7 Dialog-Box Keyboard Interface 


Key Action 

DOWN Moves the input focus to the next control that has the 
WS_GROUP style. 

ENTER Sends a WM_COMMAND message to the dialog function. The 
wParam parameter is set to 1 or the default button. 

ESCAPE Sends aWM_COMMAND message to the dialog function. The 

- wParam parameter is set to 2. 

LEFT Same as UP. 

RIGHT Same as DOWN. 

SHIFT+TAB Moves the input focus to the previous control that has the 


WS_TABSTOP style. 
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Table 1.7 Dialog-Box Keyboard Interface (continued) 


Key Action 

TAB Moves the input focus to the next control that has the WS_TAB- 
STOP style. 

UP Moves the input focus to the previous control that has the 


WS_GROUP style. 


The TAB and DIRECTION keys have no effect if the controls in the dialog box do 
not have the WS_TABSTOP or WS_GROUP style. The keys have no effect in a 
modeless dialog box if the IsDialogMessage function is not used to filter mes- 
sages for the dialog box. 


NOTE For applications that use accelerators and have modeless dialog boxes, the 
IsDialogMessage function must be called before the TranslateAccelerator function. Other- 
wise, the keyboard interface for the dialog box may not be processed correctly. 


Applications that have modeless dialog boxes and want those boxes to have the 
special keyboard interface must filter all messages retrieved from the application 
queue through the IsDialogMessage function before carrying out any other pro- 
cessing. This means that the application must pass the message to the function 
immediately after retrieving the message by using the GetMessage or PeekMes- 
sage function. Most applications that have modeless dialog boxes incorporate the 
IsDialogMessage function as part of the main message loop in the WinMain 
function. The IsDialogMessage function automatically processes any messages 
for the dialog box. This means that if the function returns a nonzero value, the 
message does not require additional processing and must not be passed to the 
TranslateMessage or DispatchMessage function. 


The IsDialogMessage function also processes the ALT+mnemonic sequence. 


Scrolling in Dialog Boxes 


In modal dialog boxes, the DIRECTION keys have specific functions that depend 
on the controls in the box. For example, the keys move the input focus from con- 
trol to control in group boxes, move the cursor in edit controls, and scroll the con- 
tents of list boxes. The DIRECTION keys cannot be used to scroll the contents of 
any dialog box that has its own scroll bars. If a dialog box has scroll bars, the 
application must provide an appropriate keyboard interface for the scroll bars. 
Note that the mouse interface for scrolling is available if the system has a mouse. 
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1.8 Scrolling Functions 


Scrolling functions control the scrolling of a window’s contents and control the 
window’s scroll bars. Scrolling is the movement of data in and out of the client 
area at the request of the user. It is a way for the user to see a document or 
graphic in parts if Windows cannot fit the entire document or graphic inside the 
client area. A scroll bar allows the user to control scrolling. The following list 
briefly describes each scrolling function: 


Function Description 

GetScrollPos “Retrieves the current position of the scroll-bar 
thumb. 

GetScrollRange Copies the minimum and maximum scroll-bar posi- 
tions for given scroll-bar positions for a specified 
scroll. 

ScrollIDC Scrolls a rectangle of bits horizontally and vertically. 

ScrollWindow Moves the contents of the client area. 

SetScrollPos Sets the scroll-bar thumb. 

SetScrollRange Sets the minimum and maximum scroll-bar posi- 
tions. 

ShowScrollBar Displays or hides a scroll bar and its controls. 


1.8.1 Standard Scroll Bars and Scroll-Bar Controls 


A standard scroll bar is a part of the nonclient area of a window. It is created with 
the window and displayed when the window is displayed. The sole purpose of a 
standard scroll bar is to let users generate scrolling requests for the window’s | 
client area. A window has standard scroll bars if it is created with the 
WS_VSCROLL or WS_HSCROLL style. A standard scroll bar is either vertical 
or horizontal. A vertical bar always appears at the right of the client area; a hori- 
zontal bar always appears at the bottom. A standard scroll bar always has the 
standard scroll-bar height and width as defined by the SM_CXVSCROLL and 
SM_CYHSCROLL system metric values. (For more information, see the GetSys- 
temMetrics function in Chapter 4, “Functions Directory.”’) 


A scroll-bar control is a control window that looks and acts like a standard scroll 
bar. But unlike a standard scroll bar, a scroll-bar control is not part of any 
window. As a separate window, a scroll-bar control can receive the input focus, 
and indicates this by displaying a flashing caret in the thumb. When a scroll-bar 
control has the input focus, the user can use the keyboard to direct the scrolling. 
Unlike standard scroll bars, a scroll-bar control provides a built-in keyboard inter- 
face. Scroll-bar controls also can be used for other purposes. For example, a 
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scroll-bar control can be used to select values from a range of values, such as a 
color from a rainbow of colors. 


1.8.2 Scroll-Bar Thumb 


The scroll-bar thumb is the small rectangle in a scroll bar. It shows the approxi- 
mate location within the current document or file of the data currently displayed 
in the client area. For example, the thumb is in the middle of the scroll bar when 
page three of a five-page.document is in the client area. 


The SetScrollPos function sets the thumb position in a scroll bar. Since 
Windows does not automatically update the thumb position when an application 
scrolls, SetScrollPos must be used to update the thumb position. The Get- 
ScrollPos function retrieves the current position. 


_ A thumb position is an integer. The position is relative to the left or upper end of 
the scroll bar, depending on whether the scroll bar is horizontal or vertical. The 
position must be within the scroll-bar range, which is defined by minimum and 
maximum values. The positions are distributed equally along the scroll bar. For 
example, if the range is 0 to 100, there are 100 positions along the scroll bar, 
each equally spaced so that position 50 is in the middle of the scroll bar. The ini- 
tial range depends on the scroll bar. Standard scroll bars have an initial range of 0 
to 100; scroll-bar controls have an empty range (both minimum and maximum 
values are zero) if no explicit range is given when the control is created. The Set- 
ScrollRange function sets new minimum and maximum values so that applica- 
tions can change the range at any time. The GetScrollRange function retrieves 
the current minimum and maximum values. The minimum and maximum values 
can be any integers. For example, a spreadsheet program with 255 rows can set 
the vertical scroll range to 1 to 255. 


If SetScrollPos specifies a position value that is less than the minimum or more 
than the maximum, the minimum or maximum value is used instead. Set- 
ScrollPos moves the thumb along the thumb positions. 


7.8.3 Scrolling Requests 


A user makes a scrolling request by clicking in a scroll bar. Windows sends the 
request to the given window in the form of WM_HSCROLL and 
WM_VSCROLL messages. The /Param parameter contains a position value and 
the handle of the scroll-bar control that generated the message (/Param is zero if 
a standard scroll bar generated the message). The wParam parameter specifies 
the type of scroll, such as scroll up one line, scroll down a page, or scroll to the 
bottom. The type of scroll is determined by which area of the scroll bar the user 
clicks. 


The user can also make a scrolling request by using the scroll-bar thumb, the 
small rectangle inside the scroll bar. The user moves the thumb by moving the 
mouse while holding the left mouse button down when the cursor is in the | 
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thumb. The scroll bar sends SB_THUMBTRACK and SB_THUMBPOSITION 
flags with a WM_HSCROLL or WM_VSCROLL message to an application as 
the user moves the thumb. Each message specifies the current position of the 
thumb. 


1.8.4 Processing Scroll Messages 


A window that permits scrolling needs a standard scroll bar or a scroll-bar con- 
trol to let the user generate scrolling requests, and a window function to process 
the WM_HSCROLL and WM_VSCROLL messages that represent the scrolling 
requests. Although the result of a scrolling request is entirely up to the window, a 
window typically carries out a scroll by moving in some direction from the cur- 
rent location or to a known beginning or end, and by displaying the data at the 
new location. For example, a word-processing application can scroll to the next 
line, the next page, or to the end of the document. 


7.8.5 Scrolling the Client Area 


The simplest way to scroll is to erase the current contents of the client area, and 
then paint the new information. This is the method an application is likely to use 
with SB_PAGEUP, SB_PAGEDOWN, SB_TOP, and SB_END requests where 
completely new contents are required. 


For some requests, such as SB_LINEUP and SB_LINEDOWN, not all the con- 
tents need to be erased, since some will still be visible after the scroll. The 

Scroll Window function preserves a portion of the client area’s contents, moves 
the preserved portion the specified amount, and prepares the rest of the client 
area for painting new information. ScrollWindow uses the BitBlt function to 
move a specific part of the client area to a new location within the client area. 
Any part of the client area that is uncovered (not in the part to be preserved) is 
invalidated and will be erased and painted over at the next WM_PAINT message. 


ScrollWindow also lets an application clip a part of the client area from the 
scroll. This is to keep items that have fixed positions in the client area, such as 
child windows, from moving. This action automatically invalidates the part of 
the client area that is to receive the new information so that the application does 
not have to compute its own clipping regions. 


1.8.6 Hiding a Standard Scroll Bar 


For standard scroll bars, if the minimum and maximum values are equal, the 
scroll bar is considered disabled and is hidden. This is the way to temporarily 
hide a scroll bar when it is not needed for the current contents of the client area. 


The SetScrollRange function hides and disables a standard scroll bar when it’ 
sets the minimum and maximum values to equal values. No scrolling requests 
can be made through the scroll bar when it is hidden. SetScrollRange enables 
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the scroll bar and shows it again when it sets the minimum and maximum values 
to unequal values. The ShowScrollBar function can also be used to hide or show 
a scroll bar. It does not affect the scroll bar’s range or thumb position. 


71.9 Menu Functions 


Menu functions create, modify, and destroy menus. A menu is an input tool ina 
Windows application that offers users one or more choices, which they can select 
with the mouse or keyboard. An item in a menu bar can display a pop-up menu, 
and any item in a pop-up menu can display another pop-up menu. In addition, a 
pop-up menu can appear anywhere on the screen. The following list briefly de- 


scribes each menu function: 


Function Description 
AppendMenu Appends a menu item to a menu. 
CheckMenultem Places or removes checkmarks next 
to pop-up menu items. 
CreateMenu Creates an empty menu. 
CreatePopupMenu Creates an empty pop-up mienu. 
DeleteMenu Removes a menu item and destroys 
. any associated pop-up menus. 
DestroyMenu Destroys the specified menu. 
DrawMenuBar Redraws a menu bar. 
EnableMenultem Enables, disables, or grays a menu 
item. 
GetMenu Retrieves a handle to the menu of a 


GetMenuCheckMarkDimensions 


specified window. 


Retrieves the dimensions of the de- 
fault menu checkmark bitmap. 


GetMenultemCount Returns the count of items in a menu. 
GetMenultemID Returns the item’s identification. 
GetMenuState Obtains the status of a menu item. 
GetMenuString Copies a menu label into a string. 
GetSubMenu Retrieves the menu handle of a pop- 


up menu. 
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Function 


GetSystemMenu 
HiliteMenultem 
InsertMenu 
LoadMenulndirect 


ModifyMenu 


RemoveMenu 


SetMenu 
SetMenultemBitmaps 


TrackPopupMenu 


1.10 Information Functions 


Description 


Accesses the System menu for copy- 
ing and modification. 


Highlights or removes the highlight- 
ing from a top-level (menu-bar) 
menu item. 


Inserts a menu item in a menu. 
Loads a menu resource. 
Changes a menu item. 


Removes an item from a menu but 
does not destroy it. 


Specifies a new menu for a window. 


Associates bitmaps with a menu item 
for display when an item is and is not 
checked. 


Displays a pop-up menu at a 
specified screen location and tracks 
user interaction with the menu. 


Information functions obtain information about the number and position of 
windows on the screen. The following list briefly describes each information 


function: 


Function 
AnyPopup > 
ChildWindowFromPoint 


EnumChild Windows 
EnumTask Windows 


EnumWindows 


FindWindow 


Description — 


Indicates whether any pop-up window exists. 


Determines which child window contains a specific 
point. 


Enumerates the child windows that belong to a 
specific parent window. 


Enumerates all windows associated with a given 
task. 


Enumerates windows on the display. 


Returns the handle of a window with the given class 
and caption. : 
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Function 
GetNextWindow 
GetParent 


GetTopWindow 
GetWindow 
GetWindowTask 


IsChild 
IsWindow 


SetParent 


WindowFromPoint 


7.171 System Functions 


Description 
Returns a handle to the next or previous window. 


Retrieves the handle of the specified window’s 
parent window. 


Returns a handle to the top-level child window. 
Returns a handle from the window manager’s list. 


Returns the handle of a task associated with a 
window. 


Determines whether a window is the descendent of a 
specified window. 


Determines whether a window is a valid, existing 
window. 


Changes the parent window of a child window. 


Identifies the window containing a specified point. 


System functions return information about the system metrics, color, and time. 
The following list briefly describes each system function: 


Function 


GetCurrentTime 


GetSysColor 
GetSystemMetrics 
SetSysColors 


7.12 Clipboard Functions 


Description 


Returns the time elapsed since the system was 
booted. 


Retrieves the system color. 
Retrieves information about the system metrics. 


Changes one or more system colors. 


Clipboard functions carry out data interchange between Windows applications. 
The clipboard is the place for this interchange; it provides a place from which 
applications can pass data handles to other applications. The following list briefly 
describes each clipboard function: 


Function 


ChangeClipboardChain 


CloseClipboard 
EmptyClipboard 


EnumClipboardFormats 


GetClipboardData 
GetClipboardFormatName 
GetClipboardOwner 


GetClipboard Viewer 


GetPriorityClipboardFormat 


IsClipboardFormatAvailable 


OpenClipboard 
RegisterClipboardFormat 
SetClipboardData 
SetClipboard Viewer 


71.73 Error Functions 
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Description 


Removes a window from the chain of 
clipboard viewers. 


Closes the clipboard. 


Empties the clipboard and reassigns 
clipboard ownership. 


Enumerates the available clipboard 
formats. 


Retrieves data from the clipboard. 
Retrieves the clipboard format. 


Retrieves the window handle as- 
sociated with the current clipboard 
Owner. 


Retrieves the handle of the first 
window in the clipboard viewer chain. 


Retrieves data from the clipboard in 
the first format in a prioritized format 
list. 


Returns TRUE if the data in the 
given format is available. 


Opens the clipboard. 
Registers a new clipboard format. 
Copies a handle for data. 


Adds a handle to the clipboard 
viewer chain. 


Error functions display errors and prompt the user for a response. The following 


list briefly describes each error function: 


Function Description 


Flash Window 


MessageBeep 


MessageBox 


Flashes the window by inverting its active/inactive 
State. 


Generates a beep on the system speaker. 


Creates a window with the given text and caption. 
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7.14 Caret Functions 


Caret functions affect the Windows caret, which is a flashing line, block, or bit- 
map that marks a location in a window’s client area. The caret is especially use- 
ful in word-processing applications to mark a location in text for keyboard 
editing. These functions create, destroy, display, hide, and alter the blink time of 
the caret. The following list briefly describes each.caret function: 


Function Description 

CreateCaret Creates a caret. 

DestroyCaret Destroys the current caret. 

GetCaretBlinkTime Returns the caret flash rate. 

GetCaretPos Returns the current caret position. 

HideCaret Removes a caret from a given window. 

SetCaretBlinkTime Establishes the caret flash rate. 

SetCaretPos Moves a caret to the specified position. 

ShowCaret . Displays the newly created caret or redisplays a hid- 
den caret. 


1.14.1 Creating and Displaying a Caret 


Windows forms a caret by inverting the pixel color within the rectangle given by 
the caret’s position and its width and height. Windows flashes the caret by alter- 

nately inverting the display, and then restoring it to its previous appearance. The 
caret blink time (in milliseconds) defines the elapsed time between inverting and 
restoring the display. A complete flash (on-off-on) takes twice the blink time. 


The CreateCaret function creates the caret shape and assigns ownership of the 
caret to the given window. The caret can be solid or gray, or, for bitmap carets, 
any desired pattern. The caret can have any shape, but typical shapes are a line, a 
solid block, a gray block, and a pattern, as shown in Figure 1.1: 
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Figure 1.1 Caret Shapes 


Windows displays a solid caret by inverting everything in the rectangle defined 
by the caret’s width and height. For a gray caret, Windows inverts every other 
pixel. For a pattern, Windows inverts only the white bits of the bitmap that de- 
fines the pattern. The width and height of a caret are given in logical units, which 
means they are subject to the window’s mapping mode. 


1.14.2 Sharing the Caret 


There is only one caret, so only one caret shape can be active at a time. Applica- 
tions must cooperatively share the caret to prevent undesired effects. Windows 
does not inform an application when a caret is created or destroyed, so to be 
cooperative a window should create, move, show, and hide a caret only when it 
has the input focus or is active. A window should destroy the caret before losing 
the input focus or becoming inactive. 


Bitmaps for the caret can be created by using the CreateBitmap function, or 
loaded from the application’s resources by using the LoadBitmap function. Bit- 
maps loaded from resources can be created by using the SDKPaint program and 
added to an application’s resources by using the Resource Compiler. (For more 
information about the Resource Compiler, see Tools.) 


71.15 Cursor Functions 


Cursor functions set, move, show, hide, and confine the cursor. The cursor is a 
bitmap, displayed on the display screen, that shows a current location. The fol- 
lowing list briefly describes each cursor function: 
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Function Description 

ClipCursor | Restricts the cursor to a given rectangle. © 

CreateCursor Creates a cursor from two bit masks. 

DestroyCursor Destroys a cursor created by the CreateCursor func- 
tion. 

GetCursorPos Stores the cursor position (in screen coordinates). 

LoadCursor Loads a cursor from the resource file. 

SetCursor _ Sets the cursor shape. 

SetCursorPos Sets the position of the cursor. 

ShowCursor Increases or decreases the cursor display count. 


1.15.1 Pointing Devices and the Cursor 


When a system has a mouse (or any other type of pointing device), the cursor 
shows the current location of the mouse. Windows automatically displays and 
moves the cursor when the mouse is moved. If a system does not have a mouse, 
Windows does not automatically display or move the cursor. Applications can 
use the cursor functions to display or move the cursor when a system does not 
have a mouse. 


1.15.2 Displaying and Hiding the Cursor 


In a system without a mouse, Windows does not display or move the cursor un- 
less the user chooses certain system commands, such as commands for sizing and 
moving. This means that after a call to SetCursor, the cursor remains on the 
screen until a subsequent call to SetCursor with a NULL parameter removes the 
cursor, or until a system command is carried out. Applications that wish to use 
the cursor without a mouse usually simulate mouse input by using keyboard 
keys, such as the DIRECTION keys, and display and move the cursor by using the 
cursor functions. 


The ShowCursor function shows or hides the cursor. It is used to temporarily 
hide the cursor, and then restore it without changing the current cursor shape. 
This function actually sets an internai counter that determines whether the cursor 
should be drawn. Hiding and showing are accumulative, so hiding the cursor five 
times requires that it be shown five times before the cursor will be drawn. 


7.15.3 Positioning the Cursor 


The SetCursorPos and GetCursorPos functions set and retrieve the current 
screen coordinates of the cursor. Although the cursor can be set at a location 
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other than the current mouse location, if the system has a mouse, the next mouse 
movement will redraw the cursor at the mouse location. The SetCursorPos and 
GetCursorPos functions are most often used in applications that use the key- 
board and specified key strokes to move the cursor. Notice that screen coordi- 
nates are not affected by the mapping mode in a window’s client area. 


7.15.4 The Cursor Hotspot and Confining the Cursor 


A cursor has a hotspot. When Windows draws the cursor, it always places the 
hotspot over the point on the display screen that represents the current position of 
the mouse or keyboard DIRECTION key. For example, the hotspot on the pointer is 
the point at the tip of the arrow. 


The ClipCursor function confines the cursor to a given rectangle on the display 
screen. The cursor can move to the edge of the rectangle but cannot move out of 
it. ClipCursor is typically used to restrict the cursor to a given window such as a 
dialog box that contains a warning about a serious error. The rectangle is always 
given in screen coordinates and does not have to be within the window of the cur- 
rently running application. 


1.15.5 Creating a Custom Cursor 


The SetCursor function sets the cursor shape and draws the cursor. When a sys- 
tem has a mouse, Windows automatically changes the shape of the cursor when it 
crosses a window border or enters a different part of a window, such as a title on 
menu bar. It uses standard cursor shapes for the different parts of the screen, such 
as a pointer in a title bar. The SetCursor function lets an application delete the 
standard cursor and draw its own custom cursor. The cursor keeps its new shape 
until the mouse moves or a system command is carried out. 


71.16 Hook Functions 


Hook functions manage system hooks, which are shared resources that install a 
specific type of filter function. A filter function is an application-supplied call- 
back function, specified by the SetWindowsHook function, that processes 
events before they reach any application’s message loop. Windows sends mes- 
sages generated by a specific type of event to filter functions installed by the 
same type of hook. The following list briefly describes each hook function: 


Function Description 


CallMsgFilter Passes a message and other data to the current 
message-filter function. 


DefHookProc Calls the next filter function in a filter-function 
chain. 
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Function Description 
Set WindowsHook Installs a system and/or application filter function. 


Unhook WindowsHook Removes a Windows filter function from a filter- 
function chain. 


1.16.1 Filter-Function Chain 


A filter-function chain is a series of connected filter functions for a particular sys- 
tem hook. For example, all keyboard filter functions are installed by WH_KEY- 
BOARD and all journaling-record filter functions are installed by 
WH_JOURNALRECORD. Applications pass these filter functions to the system 
hooks with calls to the SetWindowsHook function. Each call adds a new filter 
function to the beginning of the chain. Whenever an application passes a filter 
function to a system hook, it must reserve space for the address of the next filter 
function in the chain. SetWindowsHook returns this address. 


Once each filter function completes its task, it must call the DefHookProc func- 
tion. DefHookProc uses the address stored in the location reserved by the appli- 
cation to access the next filter function in the chain. 


To remove a filter function from a filter chain, an application must call the Un- 
hook WindowsHook function with the type of hook and a pointer to the function. 


There are five types of standard window hooks and two types of debugging 
hooks. Table 1.8 lists each type and describes its purpose: 


Table 1.8 | System Hooks 


Type Purpose 

WH_CALLWNDPROC Installs a window function filter. 

WH_GETMESSAGE Installs a message filter (on debugging ver- 
sions only). 

WH_JOURNALPLAYBACK Installs a journaling playback filter. 

WH_JOURNALRECORD Installs a journaling record filter. 

WH_KEYBOARD Installs a keyboard filter. 

WH_MSGFILTER Installs a message filter. 

WH_SYSMSGFILTER Installs a system-wide message filter. 


NOTE The WH_CALLWNDPROC and WH_GETMESSAGE hooks will affect system perform- 
ance. They are supplied for debugging purposes only. 
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1.16.2 Installing a Filter Function 


To install a filter function, an application must do the following: 


1. Export the function in its module definition file. 
2. Obtain the function’s address by using the MakeProclInstance function. 


3. Call the SetWindowsHook function, specifying the type of hook function — 
(see Table 1.8, “System Hooks’’) and the address of the function (returned by 
MakeProclInstance). 


4. Store the return value from SetWindowsHook in a reserved location. This 
value is the address of the previous filter function. ji 


NOTE Filter functions and the return value from SetWindowsHook must reside in fixed Ji- 
brary code and data. This allows these hooks to operate in a large-frame EMS environment. 


1.77 Property Functions 


Property functions create and access a window’s property list. A property list is a 
storage area that contains handles for data that the application wishes to associate 
with a window. The following list briefly describes each property function: 


Function Description 

EnumProps Passes the properties of a window to an enumeration 
function. 

GetProp Retrieves a handle associated with.a string from the 
window property list. 

RemoveProp Removes a string from the property list. 

SetProp Copies a string and a data handle to a window’s 
property list. 

Using Property Lists 


Once a data handle is in a window’s property list, any application can access the 
handle if it can also access the window. This makes the property list a convenient 
way to make data (for example, alternate captions or menus for the window) 
available to the application when it wishes to modify the window. 


Every window has its own property list. When the window is created, the list is 
empty. The SetProp function adds entries to the list. Each entry contains a 
unique ANSI string and a data handle. The ANSI string identifies the handle; the 
handle identifies the data associated with the window, as illustrated in Figure 1.2: 
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ANSI String Handle 


Figure 1.2 Property List 


The data handle can identify any object or memory block that the application 
wishes to associate with the window. The GetProp function retrieves the data 
handle of an entry from the list without removing the entry. The handle can then 
be used to retrieve or use the data. The RemoveProp function removes an entry 
from the list when it is no longer needed. 


Although the purpose of the property list is to associate data with a window for 
use by the application that owns the window, the handles in a property list are ac- 
tually accessible to any application that has access to the window. This means an 
application can retrieve and use a data handle from the property list of a window 
created by another application. But using another application’s data handles must 
be done with care. Only shared, global memory objects, such as GDI drawing ob- 
jects, can be used by other applications. If a property list contains local or global 
memory handles or resource handles, only the application that has created the 
window may use them. Global memory handles can be shared with other applica- 
tions by using the Windows clipboard. (For more information, see Section 1.12, 
“Clipboard Functions.”) Local memory handles cannot be shared. 


The contents of a property list can be enumerated by using the EnumProps func- 
tion. The function passes the string and data handle of each entry in the list to an 
application-supplied function. The application-supplied function can carry out 
any task. 


The data handles in a property list always belong to the application that created 
them. The property list itself, like other window-related data, belongs to 
Windows. A window’s property list is actually allocated in the the USER heap, 
the local heap of the USER library. Although there is no defined limit to the num- 
ber of entries in a property list, the actual number of entries depends on how 
much room is available in the USER heap. This depends on how many windows, 
window classes, and other window-related objects have been created. 


The application creates the entries in a property list. Before a window is de- 
stroyed or the application that owns the window terminates, all entries in the 
property list must be removed by using the RemoveProp function. Failure to re- 
move the entries leaves the property list in the USER heap and makes the space it 
occupies unusable for subsequent applications. This can ultimately cause an over- 
flow of the USER heap. Entries in the property list can be removed at any time 
by using the RemoveProp function. If there are entries in the property list when 
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the WM_DESTROY message is received for the window, the entries must be re- 
moved at that time. To ensure that all entries are removed, use the EnumProps 
function to enumerate all entries in the property list. An application should re- 
move only those properties that it added to the property list. Windows adds prop- 
erties for its own use and disposes of them automatically. An application must 
not remove properties which Windows has added to the list. 


1.18 Rectangle Functions 


Rectangle functions alter and obtain information about rectangles in a window’s 
client area. In Windows, a rectangle is defined by a RECT data structure. The 
structure contains two points: the upper-left and lower-right corners of the 
rectangle. The sides of a rectangle extend from these two points and are parallel 
to the x- and y-axes. The following list briefly describes each rectangle function: 


Function Description 

CopyRect Makes a copy of an existing rectangle. 
EqualRect — Determines whether two rectangles are equal. 
InflateRect Expands or shrinks the specified rectangle. 
IntersectRect Finds the intersection of two rectangles. 
OffsetRect Moves a given rectangle. 

PtInRect Indicates whether a specified point lies within a 


given rectangle. 
SetRectEmpty Sets a rectangle to an empty rectangle. 


UnionRect Stores the union of two rectangles. 


1.18.1 Using Rectangles in a Windows Application 


Rectangles are used to specify rectangular areas on the display or in a window, 
such as the cursor clipping area, the client repaint area, a formatting area for for- 
matted text, and the scroll area. Rectangles are also used to fill, frame, or invert 
an area in the client area with a given brush, and to retrieve the coordinates of a 
window or a window’s client area. 


Since rectangles are used for many different purposes, the rectangle functions do 
not use an explicit unit of measure. Instead, all rectangle coordinates and dimen- 
sions are given in signed, logical values. The actual units are determined by the 
function in which the rectangle is used. 
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1.18.2 Rectangle Coordinates 


Coordinate values for a rectangle can be within the range —32,768 to 32,767. 
Widths and heights, which must be positive, are within the range O to 32,767. 
This means that a rectangle whose left and right sides or whose top and bottom 
are further apart than 32,768 units is not valid. Figure 1.3 shows a rectangle 
whose upper-left corner is left of the origin, but whose width is less than 32,767: 


y (16000, 2000) 


(-16000, -2000) 


—— _ >x cxxyccyemlyv 
Width = 16000 — (—16000) = 32000 <= 32767 


Figure 1.3 Rectangle Limits 


1.18.3 Creating and Manipulating Rectangles 


The SetRect function creates a rectangle, the CopyRect function makes a copy 
of a given rectangle, and the SetRectEmpty function creates an empty.rectangle. 
An empty rectangle is any rectangle that has zero width, zero height, or both. 


The InflateRect function increases or decreases the width and height of a 
rectangle. It adds or removes width from both ends of the rectangle, or adds or re- 
moves height from both the top and bottom of the rectangle. 


' The OffsetRect function moves the rectangle by a given amount. It moves the 
comers of the rectangle by adding the given x and y amounts to the corner coordi- 
nates. 


The PtInRect function determines whether a given point lies within a given 
rectangle. The point is in the rectangle if it lies on the left or top side or is 
completely within the rectangle. 


The IsRectEmpty function determines whether the given rectangle is empty. 


The IntersectRect function creates a new rectangle that is the intersection of two 
existing rectangles. The intersection is the largest rectangle contained in both ex- 
isting rectangles. The intersection of two rectangles is shown in Figure 1.4: 
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Rectangle 1 


Rectangle 2 


Intersection 


Figure 1.4 Intersection of Two Rectangles 


The UnionRect function creates a new rectangle that is the union of two existing 
rectangles. The union is the smallest rectangle that contains both existing 
rectangles. The union of two rectangles is shown in Figure 1.5: 


Union 


Union 
ro Oe On" 


Rectangle 1 


Rectangle 2 


Figure 1.5 Union of Two Rectangles 


For information about functions that draw ellipses and polygons, see Section 
2.10, “Ellipse and Polygon Functions.” 


7.19 Summary 


Window manager interface functions process messages, create, move, or alter a 
window, or create system output. For more information on topics related to 
window manager interface functions, see the following: 
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Topic 


Function descriptions 


Windows messages 


Windows data types and 
structures 


Using the Resource 
Compiler 


General information on 
Windows programming 


Creating and managing a 
window 


Handling input 


Icons 
Menus 


Controls and dialog boxes 
Creating icons and cursors 


Designing dialog boxes 


Reference 


Reference, Volume 1: Chapter 4, “Functions 
Directory” 


Reference, Volume 1: Chapter 5, “Messages 
Overview,” and Chapter 6, “Messages 
Directory” 


Reference, Volume 2: Chapter 7, “Data Types 
and Structures” 


Reference, Volume 2: Chapter 8, “Resource 
Script Statements” 


Tools: Chapter 3, “Compiling Resources: 
The Resource Compiler” 


Guide to Programming: Chapter 1, “An 
Overview of the Windows Environment” 


Guide to Programming: Chapter 2, “A 
Generic Windows Application” 


Guide to Programming: Chapter 4, 
“Keyboard and Mouse Input,” and Chapter 
6, “The Cursor, the Mouse, and the 
Keyboard” 


Guide to Programming: Chapter 5, “Icons” 
Guide to Programming: Chapter 7, “Menus” 


Guide to Programming: Chapter 8, 
“Controls,” and Chapter 9, “Dialog Boxes” 


Tools: Chapter 4, “Designing Images: 
SDKPaint” 


Tools: Chapter 5, “Designing Dialog Boxes: 
The Dialog Editor” 


Chapter 


2 


_ Graphics Device Interface 
Functions 


This chapter describes the functions that perform device-independent graphics 
operations within a Windows application, including creating a wide variety of 
line, text, and bitmap output on many output devices. These functions constitute 
the Windows graphics device interface (GDI). 


The chapter covers the following function categories: 


m= Device-context functions 

= Drawing-tool functions 

= Color-palette functions 

= Drawing-attribute functions 
= Mapping functions 

= Coordinate functions 

= Region functions 

= Clipping functions 

= Line-output functions 

= Ellipse and polygon functions 
= Bitmap functions 

= Text functions 

™ Font functions 

= Metafile functions 

= Printer-control functions 

= Printer-escape function 


= Environment functions © 
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2.1 De vice-Context Functions 


Device-context functions create, delete, and restore device contexts (DC). A 
device context is a link between a Windows application, a device driver, and an 
output device, such as a printer or plotter. 


Figure 2.1 shows the flow of information from a Windows application through a 
device context and a device driver to an output device: 


1 _[019) GDI 


Output 


Device 
driver 


Device 
context 


Application device 


Figure 2.1 Information Flow to an Output Device 


Any Windows application can use GDI functions to access an output device. 
GDI passes calls (which are device independent) from the application to the 
device driver. The device driver then translates the calls into device-dependent 
operations. 


The following list briefly describes each device-context function: 


Function Description 

CreateCompatibleDC Creates a memory device context. 

CreateDC Creates a device context. 

CreateIC Creates an information context. 

DeleteDC Deletes a device context. 

GetDCOrg Retrieves the origin of a specified device context. 
RestoreDC Restores a device context. 


SaveDC Saves the current state of the device context. 
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2.1.1 Device-Context Attributes 


Device-context attributes describe selected drawing objects (pens and brushes), 
the selected font and its color, the way in which objects are drawn (or mapped) to 
the device, the area on the device available for output (clipping region), and other 
important information. The data structure that contains these attributes is called 


the DC data block. 


Table 2.1 lists the default device-context attributes and the GDI functions that af- 


fect or use these attributes: 


Table 2.1 


Attribute 


Background color 
Background mode 


Bitmap 


Brush 


Brush origin 


Clipping region 


Color palette 


Current pen position 
Drawing mode 
Font 


Default 


White 
OPAQUE 
No default 


WHITE_BRUSH 


(0,0) 


Display surface 


DEFAULT_PALETTE 


(0,0) 
R2_COPYPEN 
SYSTEM_FONT 


Default Device-Context Attributes and Related GDI Functions 


GDI Functions 


SetBkColor | 
SetBkMode 


CreateBitmap 
CreateBitmapIndirect 
CreateCompatible- 
Bitmap 

SelectObject 


CreateBrushIndirect 
CreateDIBPatternBrush 
CreateHatchBrush 
CreatePatternBrush 
CreateSolidBrush 
SelectObject 


SetBrushOrg 
UnrealizeObject 


' ExcludeClipRect 


IntersectClipRect 
OffsetClipRgn 
SelectClipRgn 


CreatePalette 
RealizePalette 
SelectPalette 


MoveTo 
SetROP2 


CreateFont 
CreateFontIndirect 
SelectObject 
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Table 2.1 Default Device-Context Attributes and Related GDI Functions 


(continued) 
Attribute Default GDI Functions 
Intercharacter spacing 0 SetTextCharacterExtra 
Mapping mode MM_TEXT SetMapMode 
Pen BLACK_PEN CreatePen 
CreatePenIndirect 
SelectObject 
Polygon-filling mode ALTERNATE SetPoly FillMode 
Stretching mode BLACKONWHITE SetStretchBltMode 
Text color Black SetTextColor 
Viewport extent (1,1) Set ViewportExt 
Viewport origin (0,0) Set ViewportOrg 
Window extent (1,1) Set WindowExt 
Window origin (0,0) SetWindowOrg 


2.1.2 Saving a Device Context 


Occasionally, it is necessary to save a device context so that the original at- 
tributes will be available at a later time. For example, a Windows application 
may need to save its original clipping region so that it can restore the client 
area’s original state after a series of alterations occur. The SaveDC and Re- 
storeDC functions make this possible. 


2.1.3 Deleting a Device Context 


The DeleteDC function deletes a device context and ensures that shared 
resources are not removed until the last context is deleted. The device driver is a 
shared resource. 


2.1.4 Compatible Device Contexts 


The CreateCompatibleDC function causes Windows to treat a portion of 
memory as a virtual device. This means that Windows prepares a device context 
that has the same attributes as the device for which it was created, but the device 
context has no connected output device. To use the compatible device context, 
the application creates a compatible bitmap and selects it into the device context. 
Any output it sends to the device is drawn in the selected bitmap. Since the 
device context is compatible with some actual device, the context of the bitmap 
can be copied directly to the actual device, or vice versa. This also means that the 
application can send output to memory (prior to sending it to the device). Note 


Graphics Device Interface Functions 2-5 


that the CreateCompatibleDC function works only for devices that have BitBlt 
capabilities. 


2.1.5 Information Contexts 


The CreateIC function creates an information context for a device. An informa- 
tion context is a device context with limited capabilities; it cannot be used to 
write to the device. An application uses an information context to gather informa- 
tion about the selected device. Information contexts are useful in large applica- 
tions that require memory conservation. 


By using an information context and the GetDeviceCaps function, you can ob- 
tain the following device information: 

m Device technology 

m™ Physical display size 

= Color capabilities of the device 

= Color-palette capabilities of the device 

m= Drawing objects available on the device 

= Clipping capabilities of the device 

= Raster capabilities of the device 

m Curve-drawing capabilities of the device 
Line-drawing capabilities of the device 

= Polygon-drawing capabilities of the device 


m= Text capabilities of the device 


2.2 Drawing-Tool Functions 


Drawing-tool functions create and delete the drawing tools that GDI uses when it 
creates output on a device or display surface. The following list briefly describes 
each drawing-tool function: 

Function Description 

CreateBrushIndirect Creates a logical brush. 


CreateDIBPatternBrush Creates a logical brush that has a pattern defined by 
a device-independent bitmap (DIB). 


CreateHatchBrush Creates a logical brush that has a hatched pattern. 
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Function Description 

CreatePatternBrush Creates a logical brush that has a pattern defined by 
a memory bitmap. 

CreatePen Creates a logical pen. 

CreatePenIndirect Creates a logical pen. 

CreateSolidBrush Creates a logical brush. 

DeleteObject Deletes a logical pen, brush, font, bitmap, or region. 

EnumObjects Enumerates the available pens or brushes. 

GetBrushOrg Retrieves the current brush origin for a device con- 
text. 

GetObject Copies the bytes of logical data that define an object. 

GetStockObject Retrieves a handle to one of the predefined stock 
pens, brushes, fonts, or color palettes. 

SelectObject Selects an object as the current object. 

SetBrushOrg Sets the origin of all brushes selected into a given 


device context. 


UnrealizeObject Directs GDI to reset the origin of the given brush. 


2.2.1 Drawing-Tool Uses 


A Windows application can use any of three tools when it creates output: a bit- 
map, a brush, or a pen. An application can use the pen and brush together, outlin- 
ing a region or object with the pen and filling the region’s or object’s interior 
with the brush. GDI allows the application to create pens with solid colors, bit- 
maps with solid or combination colors, and brushes with solid or combination 
colors. (The available colors and color combinations depend on the capabilities 
of the intended output device.) 


Brushes 


There are seven predefined brushes available in GDI; an application selects any 
one of them by using the GetStockObject function. The following list describes 
these brushes: 


= Black 
m Dark-Gray 
m= Gray 


= Hollow 


Graphics Device Interface Functions 2-7 
= Light-Gray 
# Null 
= White 
There are six hatched brush patterns; an application can select any one of these 
patterns by using the CreateHatchBrush function. (A hatch line is a thin line 
that appears at regular intervals on a solid background.) The following list de- 
scribes these hatch patterns: 
™ Backward Diagonal 
= Cross 
= Diagonal Cross 
= Forward Diagonal 
= Horizontal 
a Vertical 


Figure 2.2 shows each hatched brush pattern. A simple Windows application 
created this figure: 


HS_HORIZONTAL HS_BDIAGONAL HS_FDIAGONAL 


= \\ 


HS_VERTICAL HS CROSS HS_DIAGCROSS 
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Figure 2.2 Hatched Brush Patterns 


SS 
SS 


=H 


x 
RK 


.) 


2-8 Reference — Volume 1 


2.2.2 Color 


Pens 


There are three predefined pens available in GDI; an application selects any one 
of them by using the GetStockObject function. The following list describes 
these pens: 


= Black 
= Null 
= White 


In addition to selecting a stock pen, an application creates an original pen by 
using the GDI CreatePen function. This function allows the application to select 
one of six pen styles, a pen width, and a pen color (if the device has color capa- 
bilities). The pen style can be solid, dashed, dotted, a combination of dots and 
dashes, or null. The pen width is the number of logical units GDI maps to a cer- 
tain number of pixels (this number is dependent on the current mapping mode if 
the pen is selected into a device context). The pen color is an RGB color value. 


Figure 2.3 shows a variety of pen patterns obtained from calls to the CreatePen 
function. A simple Windows application created this figure: 


Solid Line width of 1 
Dash Line width of 4 
Dot Line width of 7 
Dash and dot Line width of 10 


Dash and two dots Line width of 13 


Figure 2.3 Pen Patterns 


Many of the GDI functions that create pens and brushes require that the calling 
application specify a color in the form of a COLORREF value. ACOLORREF 
value specifies color in one of three ways: 

= Asanexplicit RGB value 


= Asan index to a logical-palette entry 


= Asa palette-relative RGB value 
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The second and third methods require the application to create a logical palette. 
Section 2.3, “Color Palette Functions,” describes Windows color palettes and the 
functions used by an application to exploit their capabilities. 


An explicit RGB COLORREF value is a long integer that contains a red, a 
green, and a blue color field. The first (low-order) byte contains the red field, the 
second byte contains the green field, and the third byte contains the blue field; 
the fourth (high-order) byte must be zero. Each field specifies the intensity of the 
color; zero indicates the lowest intensity and 255 indicates the highest. For ex- 
ample, OxOOFFO000 specifies pure blue, and OxOOOOFFOO specifies pure green. 
The RGB macro accepts values for the relative intensities of the three colors and 
returns an explicit RGB COLORREF value. When GDI receives the RGB value 
as a function parameter, it passes the RGB color value directly to the output 
device driver, which selects the closest available color on the device. The Get- 
NearestColor function returns the closest logical color to a specified logical 
color that a given device can represent. 


If the device is a plotter, the driver converts the RGB value to a single color that 
matches one of the pens on the device. 


If the device uses color raster technology and the RGB value specifies a color for 
a pen, the driver will select a solid color. If the device uses color raster tech- 
nology and the RGB value specifies a color for a brush, the driver will select 
from a variety of available color combinations. Since many color devices can dis- 
play only a few colors, the actual color is simulated by “dithering,” that is, 
mixing pixels of the colors which the display can actually render. 


If the device is monochrome (black-and-white), the driver will select black, 
white, or a shade of gray, depending on the RGB value. If the sum of the RGB 
values is zero, the driver selects a black brush. If the sum of the RGB values is 
765, the driver selects a white brush. If the sum of the RGB values is between 
zero and 765, the driver selects one of the gray patterns available. 


The GetRValue, GetG Value, and GetB Value functions extract the values for 
red, green, and blue from an explicit RGB COLORREF value. 


2.3 Color-Palette Functions 


Many color graphic displays are capable of displaying a wide range of colors. In 
most cases, however, the actual number of colors which the display can render at 
any given time is more limited. For example, a display that is potentially able to 
produce over 262,000 different colors may be able to show only 256 of those 
colors at a time because of hardware limitations. In such cases, the display device 
often maintains a palette of colors; when an application requests a color that is 
not currently displayed, the display device adds the requested color to the palette. 
However, when the number of requested colors exceeds the maximum number 
for the device, it must replace an existing color with the requested color. As a 
result, if the total number of colors requested by one or more windows exceeds 
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the number available on the display, many of the actual colors displayed will be 
incorrect. 


Windows color palettes act as a buffer between color-intensive applications and 
the system, allowing an application to use as many colors as needed without inter- 
fering with its own color display or colors displayed by other windows. When a 
window has input focus, Windows ensures that the window will display all the 
colors it requests, up to the maximum number simultaneously available on the 
display, and displays additional colors by matching them to available colors. In 
addition, Windows matches the colors requested by inactive windows as closely 
as possible to the available colors. This significantly reduces undesirable changes 
in the colors displayed in inactive windows. 


The following list briefly describes the functions an application calls to use color 


palettes: 

Function Description 

AnimatePalette Replaces entries in a logical palette; Windows maps 
the new entries into the system palette immediately. 

CreatePalette Creates a logical palette. 


GetNearestPaletteIndex Retrieves the index of a logical palette entry most 
nearly matching a specified RGB value. 


GetPaletteEntries Retrieves entries from a logical palette. 

GetSystemPaletteEntries Retrieves a range of palette entries from the system 
palette. 

GetSystemPaletteUse Determines whether an application has access to the 
full system palette. 

RealizePalette Maps entries in a logical palette to the system palette. 

SelectPalette Selects a logical palette into a device context. 

SetPaletteEntries Sets new palette entries in a logical palette; 


Windows does not map the new entries to the sys- 
tem palette until the application realizes the logical 


palette. 
SetSystemPaletteUse Allows an application to use the full system palette. 
UpdateColors Performs a pixel-by-pixel translation of each pixel’s 


current color to the system palette. This allows an 
inactive window to correct its colors without redraw- 
ing its client area. 
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2.3.1 How Color Palettes Work 


Color palettes provide a device-independent method for accessing the color capa- 
bilities of a display device by managing the device’s physical (or system) palette, 
if one is available. Typically, devices that can display at least 256 colors use a 
physical palette. 


An application employs the system palette by creating and using one or more 
logical palettes. Each entry in the palette contains a specific color. Then, instead 
of specifying an explicit value for a color when performing graphics operations, 
the application indicates which color is to be displayed by supplying an index 
into its logical palette. 


Since more than one application can use logical palettes, it is possible that the 
total number of colors requested for display can exceed the capacity of the dis- 
play device. Windows acts as a mediator among these applications. 


When a window requests that its logical palette be given its requested colors (a 
process known as realizing its palette), Windows first exactly matches entries in 
the logical palette to current entries in the system palette. 


If an exact match for a given logical-palette entry is not possible, Windows sets 
the entry in the logical palette into an unused entry in the system palette. 


Finally, when all entries in the system palette have been used, Windows takes 
these logical palette entries that do not exactly match and matches them as 
closely as possible to entries already in the system palette. To further aid this 
color matching, Windows sets aside 20 static colors (called the “default palette”) 
in the system palette to which it can match entries in a background palette. 


Windows always satisfies the color requests of the foreground window first; this 
ensures that the active window will have the best color display possible. For the 
remaining windows, Windows satisfies the color requests of the window which 
most recently received input focus, the window which was active before that one, 
and so on. 
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Figure 2.4 Palette Manager Color-Mapping Algorithm 


Figure 2.4 illustrates this process. In this figure, a hypothetical display has a sys- 
tem palette capable of containing 12 colors. The application that created Logical 
Palette 1 owns the active window and was the first to realize its logical palette, 
which consists of 8 colors. Logical Palette 2 is owned by a window which real- 
ized its logical palette while it was inactive. 


Because the active window was active when it realized its palette, Windows 
mapped all of the colors in Logical Palette 1 directly to the system palette. 


Three of the colors (1, 3, and 5) in Logical Palette 2 are identical to colors in the 
system palette; to save space in the palette, then, Windows simply matched those 
colors to the existing system colors when the second application realized its 
palette. Colors 0, 2, 4, and 6 were not already in the system palette, however, and 
so Windows mapped those colors into the system palette. 


Because the system palette is now full, Windows was not able to map the remain- 
ing two colors (which do not exactly match existing colors in the system palette) 
into the system palette. Instead, it matched them to the closest colors in the sys- 
tem palette. 


2.3.2 Using a Color Palette 


Before drawing to the display device using a color palette, an application must 
first create a logical palette by calling the CreatePalette function and then call 
SelectPalette to select the palette for the device context (DC) for the output 
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device for which it will be used. An application cannot select a palette into a 
device context using the SelectObject function. 


All functions which accept a color parameter accept an index to an entry in the 
logical palette. The palette-index specifier is a long integer value with the first bit 
in its high-order byte set to 1 and the palette index in the two low-order bytes. 
For example, 0x01000005 would specify the palette entry with an index of 5. 
The PALETTEINDEX macro accepts an integer value representing the index of 
a logical-palette entry and returns a palette-index COLORREF value which an 
application can use as a parameter for GDI functions that require a color. 


An application can also specify a palette index indirectly by using a palette-rela- 
tive RGB COLORREF value. If the target display device supports logical 
palettes, Windows matches the palette-relative RGB COLORREF value to the 
closest palette entry; if the target device does not support palettes, then the RGB 
value is used as though it were an explicit RGB COLORREF value. The palette- 
relative RGB COLORREF value is identical to an explicit RGB COLORREF 
value except that the second bit of the high-order byte is set to 1. For example, 
0x02FF0000 would specify a palette-relative RGB COLORREF value for pure 
blue. The PALETTERGB macro accepts values for red, green and blue, and re- 
turns a palette-relative RGB COLORREF value which an application can use as 
a parameter for GDI functions that require a color. 


If an application does specify an RGB value instead of a palette entry, Windows 
will use the closest matching color in the default palette of 20 static colors. 


NOTE  \f the source and destination device contexts have selected and realized different 
palettes, the BitBIt function does not properly move bitmap bits to or from a memory device 
context. In this case, you must call the GetDIBits with the wUsage parameter set to 
DIB_RGB_COLORS to retrieve the bitmap bits from the source bitmap in a device-inde- 
pendent format. You then use the SetDIBits function to set the retrieved bits in the destina- 
tion bitmap. This ensures that Windows will properly match colors between the two device 
contexts. 


BitBlt can successfully move bitmap bits between two screen display contexts, even if they 
have selected and realized different palettes. The StretchBlt function properly moves bitmap 
bits between device contexts whether or not they use different palettes. 


2.4 Drawing-Attribute Functions 


Drawing-attribute functions affect the appearance of Windows output, which has 
four forms: line, brush, bitmap, and text. The following list describes each draw- 
ing-attribute function: 
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Function Description 

GetBkColor Returns the current background color. 
GetBkMode Returns the current background mode. 
GetPolyFillMode Retrieves the current polygon-filling ode. 
GetROP2 Retrieves the current drawing mode. 
GetStretchBltMode Retrieves the current stretching mode. 
GetTextColor Retrieves the current text color. 
SetBkColor Sets the background color. 

SetBkMode Sets the background mode. 
SetPolyFillMode Sets the polygon-filling mode. 
SetROP2 Sets the current drawing mode. 
SetStretchBitMode Sets the stretching mode. 
SetTextColor Sets the text color. 


2.4.1 Background Mode and Background Color 


Line output can be solid or broken (dashed, dotted, or a combination of the two). 
If it is broken, the space between the breaks can be filled by setting the back- 
ground mode to OPAQUE and selecting a color. By setting the background mode 
to TRANSPARENT, the space between breaks is left in its original state. The 
SetBkMode and SetBkColor functions accomplish this task. 


Brush output is solid, patterned, or hatched. The space between hatch marks can 
be filled by setting the background mode to OPAQUE and selecting a color. 


When Windows creates brush output on a display, it combines the existing color 
on the display surface with the brush color to yield a new and final color; this is a 
binary raster operation. If the default raster operation is not appropriate, a new 
one is chosen by using the SetROP2 function. 


2.4.2 Stretch Mode 


If an application copies a bitmap to a device and it is necessary to shrink or ex- 
pand the bitmap before drawing, the effects of the StretchBlt and StretchDIBits 
functions can be controlled by calling SetStretchBltMode to set the current 
stretch mode for a device context. The stretch mode determines how lines elimi- 
nated from the bitmap are combined. 


2.4.3 Text Color 
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The appearance of text output is limited only by the number of available fonts 
and the color capabilities of the output device. The SetBkColor function sets the 
color of the text background (the unused portion of each character’s cell) and the 
SetTextColor function sets the color of the character itself. 


2.5 Mapping Functions 


Mapping functions alter and retrieve information about the GDI mapping modes. 
In order to maintain device independence, GDI creates output in a logical space 
and maps it to the display. The mapping mode defines the relationship between 
units in the logical space and pixels on a device. The following list briefly de- 
scribes each mapping function: 


Function 
GetMapMode 
GetViewportExt 
GetViewportOrg 
GetWindowExt 
GetWindowOrg 
Offset ViewportOrg 
OffsetWindowOrg 
ScaleViewportExt 
ScaleWindowExt 
SetMapMode 

Set ViewportExt 
Set ViewportOrg 
SetWindowExt 
SetWindowOrg 


Description 

Retrieves the current mapping mode. 
Retrieves a device context’s viewport extents. 
Retrieves a device context’s viewport origin. 
Retrieves a device context’s window extents. 
Retrieves a device context’s window origin. 
Modifies a viewport origin. 

Modifies a window origin. 

Modifies the viewport extents. 

Modifies the window extents. 

Sets the mapping mode of a specified device context. 
Sets a device context’s viewport extents. 

Sets a device context’s viewport origin. 

Sets a device context’s window extents. 


Sets a device context’s window origin. 
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There are eight different mapping modes: MM_ANISOTROPIC, MM_HIEN- 
GLISH, MM_HIMETRIC, MM_ISOTROPIC, MM_LOENGLISH, 
MM_LOMETRIC, MM_TEXT, and MM_TWIPS. Each mode has a specific use 
in a Windows application. Table 2.2 summarizes the eight GDI mapping modes: 


Table 2.2 GDI Mapping Modes 


Mapping Mode Intended Use 

MM_ANISOTROPIC Used in applications that map one logical unit to an arbi- 
trary physical unit. The x- and y-axes are arbitrarily 
scaled. 

MM_HIENGLISH Used in applications that map one logical unit to 0.001 
inch. Positive y extends upward. 

MM_HIMETRIC Used in applications that map one logical unit to 0.01 


millimeter. Positive y extends upward. 


MM_ISOTROPIC Used in applications that map one logical unit to an arbi- 
trary physical unit. One unit along the x-axis is always 
equal to one unit along the y-axis. 

MM_LOENGLISH Used in applications that map one logical unit to 0.01 
inch. Positive y extends upward. 


MM_LOMETRIC Used in applications that map one logical unit to 0.1 mil- 
limeter. Positive y extends upward. 


MM_TEXT Used in applications that map one logical unit to one 
pixel. Positive y extends downward. 


MM_TWIPS Used in applications that map one logical unit to 1/1440 
inch (1/20 of a printer’s point). Positive y extends up- 
ward. 


2.5.1 Constrained Mapping Modes 


GDI classifies six of the mapping modes as constrained mapping modes: 
MM_HIENGLISH, MM_HIMETRIC, MM_LOENGLISH, MM_LOMETRIC, 
MM_TEXT, and MM_TWIPS. In each of these modes, one logical unit is 
mapped to a predefined physical unit. For instance, the MM_TEXT mode maps 
one logical unit to one device pixel, and the MM_LOENGLISH mode maps one 
logical unit to 0.01 inch on the device. These mapping modes are constrained be- 
cause the scaling factor is fixed, so an application cannot change the number of 
logical units that Windows maps to a physical unit. Table 2.3 shows the number 
of logical units in various mapping modes that result in a certain physical unit: 
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Table 2.3 Logical/Physical Conversion Table 


Mapping Logical Physical 
Mode Units Unit 
MM_HIENGLISH  — 1000 1 inch 
MM_HIMETRIC 100 1 millimeter 
MM_LOENGLISH 100 1 inch 
MM_LOMETRIC 10 1 millimeter 
MM_TEXT 1 Device pixel 
MM_TWIPS 1440 1 inch 


2.9.2 Partially Constrained and Unconstrained Mapping Modes 


The unconstrained mapping modes, MM_ISOTROPIC and MM_ANI- 
SOTROPIC, use two rectangular regions to derive a scaling factor and an orienta- 
tion: the window and the viewport. The window lies within the 
logical-coordinate space and the viewport lies within the physical-coordinate 
space. Both possess an origin, an x-extent, and a y-extent. The origin may be any 
one of the four corners. The x-extent is the horizontal distance from the origin to 
its opposing corner. The y-extent is the vertical distance from the origin to its op- 
posing corner. Windows creates a horizontal scaling factor by dividing the view- 
port’s x-extent by the window’s x-extent and creates a vertical scaling factor by 
dividing the viewport’s y-extent by the window’s y-extent. These scaling factors 
determine the number of logical units that Windows maps to a number of pixels. 
In addition to determining scaling factors, the window and viewport determine 
the orientation of an object. Windows always maps the window origin to the 
viewport origin, the window x-extent to the viewport x-extent, and the window y- 
extent to the viewport y-extent. 


Partially Constrained Mapping Mode 


An application creates output with equally scaled axes by using the’ 

~ MM_ISOTROPIC mapping mode. This means that Windows will map a sym- 
metrical object (for example, a square or a circle) in the logical space as a sym- 
metrical object in the physical space. In order to maintain this symmetry, GDI 
shrinks one of the viewport extents. The amount of shrinkage depends on the re- 
quested extents and the aspect ratio of the device. This mapping mode is called 
partially constrained because the application does not have complete control in al- 
tering the scaling factor. 
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Unconstrained Mapping Mode 


An application can completely alter the horizontal and vertical scaling factors by 
using the MM_ANISOTROPIC mapping mode and setting the window and view- 

_ port extents to any value after selecting this mapping mode. Windows will not 
alter either scaling factor in this mode. 


2.9.3 Transformation Equations 


GDI uses the following equations to transform logical points to device points, 
and device points to logical points: 


= Transforming logical points to device points: 
Dx = (Lx — xWO) x x VE/xWE + xVO 
Dy = (Ly — yWO) x yVE/yWE + yVO 

= Transforming device points to logical points: 
Lx = (Dx — xVO) X xWE/xVE + xWO 
Ly = (Dy — yVO) X yWE/yVE + yWO 


The following list describes the variables used in these transformation equations: 


Variable Description 

xWO Window origin x-coordinate 

ywO Window origin y-coordinate 

xWE Window extent x-coordinate 

yWE Window extent y-coordinate 

xVO Viewport origin x-coordinate 

yVO Viewport origin y-coordinate 

xVE . Viewport extent x-coordinate 

yVE . Viewport extent y-coordinate 

Lx Logical-coordinate system x-coordinate 
Ly Logical-coordinate system y-coordinate 
Dx Device x-coordinate 


Dy | Device y-coordinate 
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The following four ratios are scaling factors: 
x VE/xWE 
yVE/yWE 
xWE/xVE 
yWE/yVE 


They are used to determine the necessary stretching or compressing of logical 
units. The subtraction and addition of viewport and window origins is referred to 
as the translational component of the equation. 


2.5.4 Example: MM_TEXT 


The default mapping mode is MM_TEXT. In this mapping mode, one etoeicat 
unit is mapped to one pixel on the device or display. 


A simple Windows application created three rectangles as they appear in the logi- 
cal and physical coordinate spaces when MM_TEXT is the mapping mode, as 
shown in Figure 2.5. The drawing on the left illustrates the logical space; the 
drawing on the right illustrates the device, or physical, space. The rectangles ap- 
pear vertically elongated in the physical space because pixels on the chosen dis- 
play are longer than they are wide. The rectangles appear to be upside-down 
because positive y extends downward in the physical-coordinate system. 
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Figure 2.5 Mapping with MM_TEXT 


2.9.9 Example: MM_LOENGLISH 


A Windows application created three rectangles and mapped them from the logi- 
cal space to the physical space by using the MM_LOENGLISH mapping mode, 
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as shown in Figure 2.6. The drawing on the left illustrates how the rectangles ap- 
pear in relation to the x- and y-axes in the logical coordinate system. The drawing 
on the right illustrates how the rectangles appear in relation to the x- and y-axes 
in the physical coordinate system. 
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Figure 2.6 Mapping with MM_LOENGLISH 


2.6 Coordinate Functions 


Coordinate functions convert client coordinates to screen coordinates (or vice 
versa), and determine the location of a specific point. These functions are useful 
in graphics-intensive applications. The following list briefly describes each 
coordinate function: 


Function Description 


ChildWindowFromPoint Determines which child window contains a specified 


point. 
ClientToScreen Converts client coordinates into screen coordinates. 
DPtoLP Converts device points (that is, points relative to the 
window origin) into logical points. 
LPtoDP Converts logical points into device points. 
ScreenToClient Converts screen coordinates into client coordinates. 
WindowFromPoint Determines which window contains a specified 


point. 


2./ Region Functions 
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Region functions create, alter, and retrieve information about regions. A region is 
an elliptical or polygonal area within a window that can be filled with graphical 
output. An application uses these functions in conjunction with the clipping func- 
tions to create clipping regions. For more information about clipping functions, 
see Section 2.8, “Clipping Functions.” The following list briefly describes each 


region function: 


Function 


CombineRgn 


CreateEllipticRgn 


CreateEllipticRgnIndirect 


CreatePolygonRgn 
CreatePolyPolygonRgn 


CreateRectRgen 
CreateRectRgnIndirect 
CreateRoundRectRgn 
EqualRgn 


FillRgn 


FrameRgn 


GetRgnBox 


InvertRgn 
OffsetRgn 
PaintRgn 


PtInRegion 


Description 


Combines two existing regions into a 
new region. 


Creates an elliptical region. 
Creates an elliptical region. 
Creates a polygonal region. 


Creates a region consisting of a series 
of closed polygons that are filled as 
though they were a single polygon. 


Creates a rectangular region. 
Creates a rectangular region. 
Creates a rounded rectangular region. 


Determines whether two regions are 
identical. 


Fills the given region with a brush 
pattern. 


Draws a border for a given region. 


Retrieves the coordinates of the 
bounding rectangle of a region. 


Inverts the colors in a region. 
Moves the given region. 


Fills the region with the selected 
brush pattern. 


Tests whether a point is within a re- 
gion. 
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Function Description 


RectInRegion Tests whether any part of a rectangle 
is Within a region. 


SetRectRgn Creates a rectangular region. 


2.8 Clipping Functions 


Clipping functions create, test, and alter clipping regions. A clipping region is the 
portion of a window’s client area where GDI creates output; any output sent to 
that portion of the client area which is outside the clipping region will not be vis- 
ible. Clipping regions are useful in any Windows application that needs to save 
one part of the client area and simultaneously send output to another. The follow- 
ing list briefly describes each clipping function: 


Function Description 
ExcludeClipRect Excludes a rectangle from the clipping region. 
GetClipBox Copies the dimensions of a bounding rectangle. 
IntersectClipRect Forms the intersection of a clipping region and a 
| rectangle. 
OffsetClipRgn Moves a clipping region. 
PtVisible Tests whether a point lies in a region. 
Rect Visible Determines whether part of a rectangle lies in a re- 
gion. 
SelectClipRgn Selects a clipping region. 


2.9 Line-Output Functions 


Line-output functions create simple and complex line output with the selected 
pen. The following list briefly describes each line-output function: 


Function Description 

Are Draws an arc. 

LineDDA Computes successive points on a line. 

LineTo Draws a line with the selected pen. 

MoveTo Moves the current position to the specified point. 


Polyline Draws a set of line segments. 
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Figure 2.7 shows an arc created by using the Arc function. The upper portion of 
the illustration shows the arc as it would appear on a display; the lower portion 
shows the arc suspended in its bounding rectangle, which GDI uses to determine 
the size and shape of the arc: 


Figure 2.7 Arc and Its Bounding Rectangle 


2.9.1 Function Coordinates 


Line-output functions require coordinates in logical units, which GDI uses to 
draw a line in logical space. The use of logical units ensures device independence 
in Windows. GDI maps this line from the logical space to the physical space on 
the device. The number of logical units that GDI maps to a pixel depends on the 
current mapping mode. When GDI draws a line, it excludes the last specified 
point. For example, if the LineTo function is given the arguments (X/, Y/) and 
(X2, Y2), the line will be drawn from (XJ, Y/) to (X2—1, Y2-1). 


2.9.2 Pen Styles, Colors, Widths 


If an application draws lines and does not create a new pen, GDI uses the default 
pen. This pen is black and is one pixel wide when the mapping mode is 
MM_TEXT. An application can create a new pen of a different width, style, and 
color by using the CreatePen function. The new color is dependent on the color 
capabilities of the output device. The new style can be solid, dotted, dashed, or a 
combination of dotted and dashed. Once an application creates a new pen, it can 
select it into a display context by using the SelectObject function. 


Figure 2.8 shows simple line output created by the LineTo and MoveTo func- 
tions. The application created the rectangle on the left by using a styled pen and 
the rectangle on the right by using a solid pen: 
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Styled pen Solid pen 


Figure 2.8 Styled-Pen and Solid-Pen Rectangles 


2.10 Ellipse and Polygon Functions 


Ellipse and polygon functions draw ellipses and polygons. GDI draws the perime- 
ter of each object with the selected pen and fills the interior by using the selected 
brush. These functions are particularly useful in drawing and charting applica- 
tions. The following list briefly describes each ellipse and polygon function: 


Function Description 

Chord Draws a chord. 

DrawFocusRect Draws a rectangle in the style used to indicate focus. 

Ellipse Draws an ellipse. 

Pie Draws a pie. 

Polygon Draws a polygon. 

PolyPolygon Draws a series of closed polygons that are filled as 
though they were a single polygon. 

Rectangle Draws a rectangle. 

RoundRect Draws a rounded rectangle. 


2.10.1 Function Coordinates 


Ellipse and polygon functions require coordinates in logical units, which GDI 
uses to determine the location and size of an object in logical space. The use of 
logical units ensures device independence in Windows. GDI uses a mapping 
function to map logical units to pixels on the device. The number of logical units 
that Windows maps to a pixel depends on the current mapping mode. The default 
mapping mode, MM_TEXT, maps one logical unit to one pixel. 


When GDI draws a rectangle, it uses four arguments. The first two arguments 
specify the rectangle’s upper-left corner. The last two arguments do not actually 
specify part of the rectangle; they specify the point adjacent to the lower-right 
corner. For example, if the first point is specified by (X/, YJ) and the second 
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point is specified by (X2, Y2), the rectangle’s upper-left corner will be (XJ, Y/) 
and the lower-right corner will be (X2 — 1, Y2- 1). 


2.10.2 Bounding Rectangles 


Instead of requiring a radius or circumference measurement, the Chord, Ellipse, 
and Pie functions use a bounding rectangle to define the size of the object they 
create. The bounding rectangle is hidden; GDI uses it only to describe the ob- 
ject’s location and size. 


For information about functions that alter or obtain information about rectangles 
in a window’s client area, see Section 1.18, “Rectangle Functions.” 


2.11 Bitmap Functions 


Bitmap functions display bitmaps. A bitmap is a matrix of memory bits that, 
when copied to a device, defines the color and pattern of a corresponding matrix 
of pixels on the device’s display surface. Bitmaps are useful in drawing, charting, 
and word-processing applications because they let you prepare images in 
memory and then quickly copy them to the display. The following list briefly de- 
scribes each bitmap function: 


Function Description 

BitBit Copies a bitmap from a source to a 
destination device. 

CreateBitmap Creates a bitmap. 

CreateBitmapIndirect Creates a bitmap described in a data 
structure. 

CreateCompatibleBitmap Creates a bitmap that is compatible 
with a specified device. 

CreateDiscardableBitmap Creates a discardable bitmap that is 

compatible with a specified device. 

ExtFloodFill Fills the display surface within a 
border or over an area of a given 
color. 

FloodFill Fills the display surface within a 
border. 

GetBitmapBits Retrieves the bits in memory fora 


specific bitmap. 


GetBitmapDimension Retrieves the dimensions of a bitmap. 
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Function Description 

GetPixel Retrieves the RGB value for a pixel. 
LoadBitmap Loads a bitmap from a resource file. 
PatBit Creates a bit pattern. 

SetBitmapBits Sets the bits of a bitmap. 
SetBitmapDimension Sets the height and width of a bitmap. 
SetPixel Sets the RGB value for a pixel. 
StretchBlt Copies a bitmap from a source to a 


destination device (compresses or 
stretches, if necessary). 


2.11.1 Bitmaps and Devices 


The relationship between bitmap bits in memory and pixels on a device is device- 
dependent. On a monochrome device, the correspondence is usually one-to-one, 
where one bit in memory corresponds to one pixel on the device. 


2.11.2 Device-Independent Bitmap Functions 


Microsoft Windows version 3.0 provides a set of functions that define and 

manipulate color bitmaps which can be appropriately displayed on any device 

with a given resolution, regardless of the method by which the display represents 

color in memory. These functions translate a device-independent bitmap specifi- 

cation into the device-specific format used by the current display. The following 
* is a list of these functions: 


Function Description 


CreateDIBitmap Creates a device-specific memory bitmap from a 
device-independent bitmap (DIB) specification and 
optionally initializes bits in the bitmap. This func- 
tion is similar to CreateBitmap. 


GetDIBits Retrieves the bits in memory for a specific bitmap in 
device-independent form. This function is similar to 
GetBitmapBits. 

SetDIBits Sets a memory bitmap’s bits from a DIB. This func- 


tion is similar to SetBitmapBits. 


SetDIBitsToDevice Sets bits on a device surface directly from a DIB. 
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Function Description 


StretchDIBits Moves a device-independent bitmap (DIB) from a 
source rectangle into a destination rectangle, stretch- 
ing or compressing the bitmap as required. 


A device-independent bitmap specification consists of two parts: 


1. A BITMAPINFO data structure that defines the format of the bitmap and op- 
tionally supplies a table of colors used by the bitmap 


2. An array of bytes that contain the bitmap bit values 


Depending on the values contained in the bitmap information data structure, the 
bitmap bit values can specify explicit color (RGB) values or indexes into the 
color table. In addition, the color table can consist of indexes into the currently re- 
alized logical palette instead of explicit RGB color values. It is important to note 
that the coordinate-system origin for DIBs is the lower-left corner, not the 
Windows default upper-left corner. 


2.12 Text Functions | | | 


Text functions retrieve text information, alter text alignment, alter text justifica- 
tion, and write text on a device or display surface. GDI uses the current font for 
text output. The following list briefly describes each text function: 


Function Description 


ExtTextOut Writes a character string, within a rectangular re- 
gion, using the currently selected font. The rectangu- 
lar region can be opaque (filled with the current 
background color) and it can be a clipping region. 


GetTabbedTextExtent Computes the width and height of a line of text con- 
taining tab characters. 


GetTextAlign Returns a mask of the text alignment flags. 

GetTextExtent Uses the current font to compute the width and 
height of text. 

GetTextFace Copies the current font name to a buffer. 

GetTextMetrics Fills the buffer with metrics for the selected font. 

SetTextAlign Positions a string of text on a display or device. 


SetText Justification Justifies a text line. 


2-28 Reference — Volume 1 


Function 


TabbedTextOut 


TextOut 


2.13 Font Functions 


Description 


Writes a character string with expanded tabs, using 
the current font. 


Writes a character string using the current font. 


Font functions select, create, remove, and retrieve information about fonts. A 
font is a subset of a particular typeface, which is a set of characters that share a 


similar fundamental design. 


The following list briefly describes each font function: 


Function 


AddFontResource 
CreateFont 
CreateFontIndirect 


EnumFonts 
GetChar Width 
RemoveFontResource 


SetMapperFlags 


Description 


Adds a font resource in the specified file to the sys- 
tem font table. 


Creates a logical font that has the specified charac- 
teristics. 


Creates a logical font that has the specified charac- 
teristics. 


Enumerates the fonts available on a given device. 
Retrieves the widths of individual characters. 
Removes a font resource from the font table. 


Alters the algorithm the font mapper uses. 


A font family is a group of typefaces that have similar stroke-width and serif 
characteristics. A typeface is a set of characters (letters, numerals, punctuation 
marks, symbols) that share a common design. Font characters share very specific 
characteristics, such as point size and weight. 


Note that the terms GDI uses to describe fonts, typefaces, and families of fonts 
do not necessarily correspond to traditional typographic terms. 


The Helv typeface is an example of a familiar typeface. Available fonts within 
this typeface include 8-point Helv bold and 10-point Helv italic. 


Figure 2.9 shows several fonts from the Helv and Courier typefaces: 
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This is a line of 12 point Helv. 
This is a line of 12 point Helv bold. 
This ts a line of 12 point Helv italic. 


Thisisalineof12 point Courier. 
This isaline of 12 point Courierbold. 


Thisisalineofi2point Courieritalic. 


Figure 2.9 Fonts from Two Typefaces 


2.13.1 Font Family 


GDI organizes fonts by family; each family consists of typefaces and fonts that 
share a common design. The families are divided by stroke width and serif 
characteristics. The term stroke, which means a horizontal or vertical line, comes 
from handwritten characters composed of one or more pen strokes. The horizon- 
tal stroke is called a cross-stroke. The main vertical line is called a stem. 

Figure 2.10 shows a lowercase f composed of a cross-stroke and a stem with a 
loop at the top: 


Cross-stroke 


Stem 


Figure 2.10 Cross-Stroke and Stem 


Serifs are short cross-lines drawn at the ends of the main strokes of a letter. If a 
typeface does not have serifs, it is generally called a sans-serif (without serif) 
typeface. Figure 2.11 shows serifs: 


Serif 
Serif 


AlLL= 


Figure 2.11 Serifs 
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GDI uses five distinct family names to categorize typefaces and fonts. A sixth 
name is used for generic cases. Note that GDI’s family names do not correspond 
to traditional typographic categories. Table 2.4 lists the font-family names and 
briefly describes each family: 


Table 2.4 Font Families 


Name Description 

Dontcare Generic family name. Used when information about a font does 
not exist or does not matter. 

Decorative Novelty fonts. 

Modern Constant stroke width (fixed-pitch), with or without serifs. 
Fixed-pitch fonts are usually modern. 

Roman Variable stroke width (proportionally spaced), with serifs. 

Script Designed to look like handwriting. 

Swiss : Variable stroke width (proportionally spaced), without serifs. 


2.13.2 Character Cells 


A character is the basic element in a font. In GDI, each character is contained 
within a rectangular region known as a character cell. This rectangular region 
consists of a specific number of rows and columns, and possesses six points of 
measurement: ascent, baseline, descent, height, origin, and width. The following 
list describes these measurements: 


Measurement Description 

Ascent Specifies the distance in character-cell rows from 
the character-cell baseline to the top of the character 
cell. 

Baseline Serves as the base on which all characters stand 


(some lowercase letters have descenders, such as the 
tail of the g or y, that descend below the baseline). 


Descent Specifies the distance in character-cell rows from 
the character-cell baseline to the bottom of the 
character cell. 


Height Specifies the height of a character-cell row. 
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Measurement Description 


Origin Used as a point of reference when the character is 
written on a device or a display surface. The origin 
is the upper-left corner of the character cell. 


Width Specifies the width of a character-cell column. 
‘Figure 2.12 shows a character cell that contains an uppercase A. The baseline ap- 
pears at the top of the second row. Note that the uppercase A uses the baseline as 


its starting point. Also note that the width and height values refer to the character- 
cell width and height, not the width and height of the individual character: 


Origin 
C 
Ascent | 


Height 
ie 
ia mee + Descent 


Figure 2.12 Character-Cell Dimensions 


> 


2.13.3 Altering Characters 


Characters exist in many sizes and shapes. The following sections describe how 
characters are altered in GDI to produce a particular font. 


Italic 


For an italic font, GDI skews the characters so that they appear slanted. When 
italicized, the base of the character remains intact while the upper portion shifts 

to the right. The greatest amount of shifting occurs at the top of the character, the 
least amount at the base. Figure 2.13 shows characters before and after being itali- 
cized: 


Alia) (Alia 


These two examples illustrate the result of 
italic type. The base of each character 
remains intact while the upper portion is 
skewed to the right. 


Figure 2.13 Normal and Italic Characters 
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Bold 


A font is made bold by increasing its weight, which refers to the thickness of the 
lines or strokes that compose a character. Fonts with a heavy weight are referred 
to as bold. Figure 2.14 shows normal and bold characters: 


Alia] (Ajia| 


These two examples illustrate the result of 
varying font weight. A heavier weight gives 
youabolderfont. ~~ 


Figure 2.14 Normal and Bold Characters 


Underline 


An underline font has a line under each character. When a character is under- 
lined, a solid line appears directly below the baseline of the character cell. Figure 
2.15 shows underlined characters: 


A 


This font is underlined. 


Asolid line is drawn - 
below the baseline of 


each character cell. 


Figure 2.15 Underlined Characters 


Strikeout 


A strikeout font has a solid horizontal line drawn through each character. The 
position of this line within each character cell is constant for a given font. Figure 
2.16 shows characters that are struck out: — 
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2.13.4 Leading 


Alia 


This string of text 
illustrates the-effeet 


‘ iH a 
Figure 2.16 Strikeout Characters 


Leading is the distance from baseline to baseline of two adjacent rows of text. 
When font designers develop a font, they specify that a given amount of space 
should appear between rows. The addition of this space ensures that a character 
is not obscured by part of another character in an adjacent row. There aretwo . 
ways of adding this additional space: by inserting it within the character cells of a 
font (internal leading) or by inserting it between rows of text as they are printed 
on a device (external leading). 


Internal Leading 


Internal leading refers to the space inserted within character cells of a particular 
font. Only marks such as accents, umlauts, and tildes in foreign character sets ap- 
pear within the space allocated for internal leading. Figure 2.17 shows two rows 
of text that use internal leading: 


Internal leading Top of character cell 
2 ; . 
ii Character-cell 
baseline 
ny ] 
i Leading 
ae Character-cell 
( Bottom of baseline 


character-cell 


Figure 2.17 Internal Leading 


2-34 Reference — Volume 1 


External Leading 


External leading is space inserted between the top and bottom of character cells 
in adjacent rows of text. The font designer must specify the amount of external 
leading necessary to produce easily readable text from a particular font. External 
leading is not built into a font; you must add it before you print text on a device. 
Figure 2.18 shows external leading: 


External 
leading 


Figure 2.18 External Leading 


2.13.5 Character Set 


All fonts use a character set. A character set contains punctuation marks, numer- 
als, uppercase and lowercase letters, and all other printable characters. The de- 
signer of a character set assigns a numeric value to each element in the set. You 
use this number to access an element within the set. 


Most character sets used in Windows are supersets of the U.S. ASCII character 
set, which defines characters for the 96 numeric values from 32 to 127. There are 
four major groups of character sets: 

= ANSI 

= OEM 

= Symbol 


= Vendor specific 


ANSI Character Set 


-The ANSI character set is the most commonly used character set. The blank 
character is the first character in the ANSI character set. It has a hexadecimal 
value of 0x20, which is equivalent to the decimal value 32. The last character in 
the ANSI character set has a hexadecimal value of OxFF, which is equivalent to 
the decimal value 255. 


Many fonts specify a default character. Whenever a request is made for a 
character not in the set, this default character is given. Most fonts using the ANSI 
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2.13.6 Pitch 


character set specify the period (.) as the default character. The hexadecimal 
value for the period is 0x2E, or decimal 46 in the ANSI character set. 


Fonts use a break character to separate words and justify text. Most fonts using 
the ANSI character set specify the blank character, whose hexadecimal value is 
0x20, decimal 32. 


OEM Character Set 


Windows supports a second character set, referred to as the OEM character set. 
This is generally the character set used internally by DOS for screen display. 
Characters 32 to 127 of the OEM set are usually identical to the same characters 
in the U.S. ASCII set, which are also in the ANSI set. The remaining characters 
in the OEM set (0 to 31, and 128 to 255) correspond to the characters which may 
be shown on the computer’s DOS display, and generally differ from ANSI 
characters. 


Symbol Character Set 


The symbol character set contains special characters typically used to represent 
mathematical and scientific formulas. 


Vendor-Specific Character Sets 


Many printers and other output devices contain fonts based on character sets 
which differ from the ANSI and OEM sets, such as the EBCDIC character set. In 
such cases, the printer driver must translate from the ANSI character set to one or 
more of the sets provided by the printer or other device. 


The term pitch traditionally refers to the number of characters from a particular 
font that will fit in a single inch. GDI, however, uses this term differently. The 
term fixed-pitch refers to a font whose character-cell size is constant for each 
character. The term variable-pitch refers to a font whose character cells vary in 
size, depending on the actual width of the characters. 


Average Character Width 


Variable-pitch fonts use the average character width to specify the average width 


. of character cells in the font. Since there is no variance in character-cell width for 


fixed-pitch fonts, the average character width specifies the character width of any 
character in the fixed-pitch font. 


Maximum Character Width 


Variable-pitch fonts use the maximum character width to specify the maximum 
width of any character cell in the font. Since there is no variance in character . 
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width for fixed-pitch fonts, the maximum character width is equivalent to the 
average character width in the fixed-pitch font. 


Digitized Aspect 


When raster fonts are created, they are designed with one particular aspect ratio 
in mind. The aspect ratio is the ratio of the width and height of a device’s pixel. 
GDI maintains a record of the ideal x-aspect and y-aspect for individual fonts. 
The ideal x-aspect is the width value from the aspect ratio of the device. The 
ideal y-aspect is the height value from the aspect ratio of the device. These values 
are called the digitized aspects for x and y. The GetAspectRatioFilter function 
retrieves the setting for the current aspect-ratio filter. Windows provides a special 
filter, the aspect-ratio filter, to select fonts designed for a particular aspect ratio 
from all of the available fonts. The filter uses the aspect ratio specified by the 
SetMapperFlags function. 


Overhang 


When a particular font is not available on a device, GDI sometimes synthesizes 
that font. The process of synthesizing may add width or height to an existing 
font. Whenever GDI synthesizes an italic or bold font from a normal font, extra 
columns are added to individual character cells in that font. The difference in 
width (the extra columns) between a string created with the normal font and a 
string created with the synthesized font is called the overhang. 


2.13.7 Selecting Fonts with GDI 


GDI maintains a collection of fonts from different typefaces. In addition to this 
collection, some.devices maintain a collection of hardware fonts in their ROM. 
GDI lets you describe a font and then selects the closest matching available font 
from your description. 


GDI requires you to describe the font you want to use to create text. The font you 
describe is a logical font (it may or may not actually exist). GDI compares this 
logical font to the available physical fonts and selects the closest match. 


The process of selecting the physical font that bears the closest resemblance to 
the specified logical font is known as font mapping. GDI also maintains a font 
table. Each entry in the font table describes a physical font and its attributes. In- 
cluded in each entry is a pointer to a corresponding font resource. Figure 2.19 
shows a font table that contains fonts X, Y, and Z: 
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Font Table 


Font X information 


leading underline 
char set height 


pitch and family last char 
Font Y information 


underline 
|_pitch and family | lastchar |... | - 


Figure 2.19 A GDI Font Table 


weight 


first char 


Pointer to 
font X resource 


weight 


first char 


Pointer to 
font Y resource 


Pointer to 
font Z resource 


Font-Mapping Scheme 


GDI cannot guarantee that a physical font exists that exactly matches a requested 
logical font, so GDI attempts to pick a font that has the fewest differences from 
the requested logical font. Since fonts have many different attributes, the GDI 
font mapper assigns penalties to physical fonts whose characteristics do not 
match the characteristics of the specified logical font. The physical font with the 
fewest penalties assigned is the.one that GDI selects. 


To begin the mapping, GDI transforms the requested height and width of the logi- 
cal font to device units. This transformation depends on the current mapping 
mode and window and viewport extents. GDI then asks the device to realize the 
physical font. A device can realize a font if it can create it or a font very close to 
it. 

If the device can realized a physical font, GDI compares this font with its own set 
of fonts. If GDI has a font that more closely matches the logical font, GDI uses it. 
But if the device signals that it can take device-realized fonts only, GDI uses the 
realized font. 


If the device cannot realize a font, GDI searches its own fonts for a match. 


To determine how good a match a given physical font is to the requested logical 
font, the mapper takes the logical font and compares it one attribute at a time 
with each physical font in the system. 


Table 2.5 lists the characteristics that are penalized by GDI’s font mapper. The 
characteristics are grouped according to penalty weights, with the heaviest 
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penalty assigned to the CharSet characteristic and the lightest penalty assigned to 
the Weight, Slant, Underline, and StrikeOut characteristics. 


Table 2.5 Font-Mapping Characteristics 


Characteristic Penalty Scheme Penalty 
Weight 
CharSet If the character set does not match, the candidate 4 


font is penalized heavily. Fonts with the wrong 
character set are very rarely selected as the physi- 
cal font. There is no default character set. This 
means a logical font must alway specify the 
desired set. 


Pitch The wrong pitch is penalized heavily. If the re- 3 
quested pitch is fixed, a wrong pitch is assessed a 
greater penalty since an application that handles 
fixed pitches may not be able to handle variable- 
pitch fonts. 


Family If the font families do not match, the candidate 2 
font is penalized heavily. If a default font family ; 
is requested, no penalties are assessed. 


FaceName If the font typeface names do not match, the candi- 3 
date font is penalized heavily. If a default font 
facename is requested, no penalties are assessed. 


Height The wrong height is penalized. GDI always 2 
chooses or synthesizes a shorter font if the exact - 
height is not available. GDI can synthesize a font 
by expanding a font’s character bitmaps by an in- 
teger multiple. GDI will expand a font up to eight 
times. If a default height is requested, GDI arbi- 
trarily searches for a twelve-point font. 


Width The wrong width is penalized. GDI always 2 
chooses or synthesizes a narrower font if the exact 
width is not available. If a default width is re- 
quested, GDI assesses a penalty for any difference 
between the aspect ratio of the device and the 
aspect ratio of the font. The mapper can give unex- 
pected results if there are no fonts for the given 
aspect ratio. 


Weight Although GDI can synthesize bold, an actual bold ] 
font is preferred. The mapper penalizes for synthe- 
sizing. 

Slant Although GDI can synthesize italics, an actual 1 


italic font is preferred. The mapper penalizes for 
synthesizing. 
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Table 2.5 Font-Mapping Characteristics (continued) 


Characteristic Penalty Scheme Penalty 
Weight 
Underline Although GDI can synthesize underlining, an ac- 1 


tual underline font is preferred. The mapper 
penalizes for synthesizing. 


StrikeOut Although GDI can synthesize strikeouts, an actual 1 


strikeout font is preferred. The mapper penalizes 
for synthesizing. 


If GDI synthesizes a font, the mapper assesses a penalty that depends on the num- 
ber of times the font was replicated. Furthermore, a penalty is added if the font 
was synthesized in both directions and the synthesizing was uneven, that is, if the 
font was stretched more in one direction than the other. 


When the mapper has compared all the fonts in the system, it picks the one with 
the smallest penalty. The application should retrieve the metrics of the font to 
find out the characteristics of the font it received. 


The penalty weights listed in Table 2.5 are the default penalties used by GDI. 


Example of Font Selection 


For the purpose of this example, assume that the system font table lists only the 
three fonts shown in Figure 2.19, “A GDI Font Table,” fonts X, Y, and Z. Sup- 
pose you need to use a specific font, font Q, to create text on an output device. 
You will need to describe font Q so that GDI can choose the physical font (X, Y, 
or Z) that bears the closest resemblance to Q. 


To describe font Q, you use the CreateFont or CreateFontIndirect GDI func- 
tion. These functions create a logical font which is a description of the desired 
physical font. 


Use the SelectObject function to select the physical font that most closely 
matches logical font Q. (The SelectObject function requires that you pass a 
handle to font Q.) Once a call to the SelectObject function occurs, GDI will in- 
itiate the selection process. 
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Table 2.6 shows the physical fonts in the font table and the penalties that GDI as- 
signs to each as it tries to find a font that will match font Q. The left column 
shows the font attributes that GDI compares; the second column gives the at- 
tributes of font Q, the desired font. The attributes of fonts X, Y, and Z—the fonts 
that are actually in the system font table—are followed by the penalty values that 
GDI gives to each one. The bottom row of the table gives the penalty totals for 
each font: 


Table 2.6 Sample Font Selection Ratings 


Desired Available Fonts/Penalty Score 
Attributes Q xX ; Y Z 
CharSet ANSI OEM 4 OEM 4 ANSI 0 
Pitch Fixed Variable 3 —~Fixed 0 Variable 3 
Family Roman Modern 3. Roman 0 Modern 3 
FaceNaine Tms Pica 3 Tms 0 Elite é) 

Rmn Rmn 
Height 8 10 2 10 2 8 0 
Width 4 6 2 6 Z 4 0 
Slant None None O None 0 None 0 
Underline None None O None 0 None 0 
StrikeOut None None 0 None 0 None 0 
Penalty Total 17 8 9 


The penalty totals show that font Y has the lowest penalty score and therefore re- 
sembles font Q most closely. In this example, GDI would select font Y as the 
physical font on the output device. 


2.13.8 Font Files and Font Resources 


GDI stores information about the physical font in font files. The font file consists 
of a header and a bitmap. The font-file header contains a detailed description of 
the font. If the font file is a raster file, the font-file bitmap contains actual repre- 
sentations of the font characters. If the font file is a vector file, the font-file bit- 
map contains character strokes for the font characters. A font resource is a 
collection of one or more of these physical-font files. 
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2.14 Metafile Functions 


Metafile functions close, copy, create, delete, retrieve, play, and return informa- 
tion about metafiles. A metafile is a collection of GDI commands that creates 
desired text or images. 


Metafiles provide a convenient method of storing graphics commands that create 
text or images. Metafiles are especially useful in applications that use specific 
text or a particular image repeatedly. They are also device-independent; by creat- 
ing text or images with GDI commands and then placing the commands in a 
metafile, an application can re-create the text or images repeatedly on a variety 
of devices. Metafiles are also useful in applications that need to pass graphics 
information to other applications. 


The following list briefly describes each metafile function: 


Function Description 

CloseMetaFile Closes a metafile and creates a metafile handle. 

CopyMetaFile Copies a source metafile to a file. 

CreateMetaFile Creates a metafile display context. 

DeleteMetaFile Deletes a metafile from memory. 

EnumMetaFile Enumerates the GDI calls within a metafile. 

GetMetaFile Creates a handle to a metafile. 

GetMetaFileBits Stores a metafile as a collection of bits in a global 
memory block. 

Play MetaFile Plays the contents of a specified metafile. 

Play MetaFileRecord Plays a metafile record. 

SetMetaF ileBits Creates a memory metafile. 


2.14.1 een a Metafile 


A Windows application must create a metafile in a special device context. It can- 
not use the device contexts that the CreateDC or GetDC functions return; in- 
stead, it must use the device context that the CreateMetaFile function returns. 


Windows allows an application to use a subset of the GDI functions to create a 
metafile. This subset is the set of all GDI functions that create output (it is not 
necessary to use those functions that provide state information, such as the 
GetDeviceCaps or GetEnvironment functions). The following is a list of GDI 
functions an application can use in a metafile: 
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AnimatePalette ; Offset ViewportOrg SetDIBitsToDevice 
Arc OffsetWindowOrg SetMapMode 
BitBlt PatBit SetMapperFlags 
Chord Pie SetPixel 
CreateBrushIndirect Polygon SetPolyFillMode 
CreateDIBPatternBrush  Polyline SetROP2 
CreateFontIndirect PolyPolygon SetStretchBltMode 
CreatePatternBrush RealizePalette SetTextAlign 
CreatePenIndirect Rectangle SetTextCharExtra 
CreateRegion ResizePalette SetTextColor 
DrawText RestoreDC SetTextJustification 
Ellipse RoundRect Set ViewportExt 
Escape SaveDC Set ViewportOrg 
ExcludeClipRect Scale ViewportExt SetWindowExt 
ExtTextOut ScaleWindowExt SetWindowOrg 
Flood Fill '  SelectClipRegion StretchBlt 
IntersectClipRect SelectObject StretchDIBits 
LineTo SelectPalette TextOut 

MoveTo SetBkColor 

OffsetClipRgn SetBkMode 


To create output with a metafile, an application must follow four steps: 


1. Create a special device context by using the CreateMetaFile function. 
2. Send GDI commands to the metafile by using the special device context. 


3. Close the metafile by calling the CloseMetaFile function. This function re- 
turns a metafile handle. 


4, Display the image or text on a device by using the PlayMetaFile function, 
passing to the function the metafile handle obtained from CloseMetaFile and 
a device-context handle for the device to which the metafile is to be played. 


The device context which CreateMetaFile creates does not have default at- 
tributes of its own. Whatever device-context attributes are in effect for the output 
device when an application plays a metafile will be the defaults for the metafile. 
The metafile can change these attributes while it is playing. If the application 
needs to retain the same device-context attributes after the metafile has finished 
playing, it should save the output device context by calling the SaveDC function 
before calling PlayMetaFile. Then, when PlayMetaFile returns, the application 
can call the RestoreDC function (with —1 as the nSavedDC parameter) to restore 
the original device-context attributes. 


Although the maximum size of a metafile is a°* bytes or records, the actual size 
of a metafile is limited by the amount of memory or disk space available. 
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2.14.2 Storing a Metafile in Memory or on Disk 


An application can store a metafile in system memory or in a disk file. 


To store the metafile in memory, an application calls CreateMetafile and passes 
NULL as the function parameter. 


There are two ways of storing a metafile in a disk file: 
= When the application calls CreateMetaFile to open a metafile, it passes a 


filename as the function parameter; the metafile will then be recorded in a 
disk file. 


= After the application has created a metafile in memory, it calls the Copy- 
MetaFile function. This function accepts the handle of a memory metafile 
and the filename of the disk file which is to save the metafile. 


The GetMetaFile function opens a metafile stored in a disk file and makes it 
available for replay or modification. This function accepts the filename of a meta- 
file stored on disk and returns a metafile handle. 


2.14.3 Deleting a Metafile 


An application frees the memory which Windows uses to store the metafile by 
calling the DeleteMetafile function. This function removes a metafile from 
memory and invalidates its handle. It has no effect on disk files. 


2.14.4 Changing How Windows Plays a Metafile 


A metafile does not have to be played back in its entirety or exactly in the form 
in which it was recorded. An application can use the EnumMetaFile function to 
locate a specific metafile record. EnumMetafFile calls an application-supplied 
callback function and passes it the following: 

= The metafile device context 

= A pointer to the metafile handle table 

= A pointer to a metafile record 

= The number of associated objects with handles in the handle table 

= A pointer to application-supplied data 

The callback function can then use this information to play a single record, to 


query it, copy it, or modify it. The PlayMetaFileRecord function plays a single 
metafile record. 
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Chapter 9, “File Formats,” in Reference, Volume 2, shows the formats of the 
various metafile records and describes their contents. 


When Windows plays or enumerates the records in a metafile, it identifies each 
object with an index into a handle table. Functions that select objects (such as 
SelectObject and SelectPalette) identify the object by means of the object 
handle which the application passes to the function. 


Objects are added to the table in the order in which they are created. For ex- 
ample, if a brush is the first object created in a metafile, the brush is given index 
zero. If the second object is a pen, it is given index 1, and so on. See the descrip- 
tion of the HANDLETABLE data structure in Chapter 7, “Data Types and Struc- 
tures,” in Reference, Volume 2, for information on the format of the handle table. 


2.15 Printer-Control Functions 


Printer-control functions retrieve information about a printer and modify its in- 
itialization state. The printer driver, rather than GDI itself, provides these func- 
tions. The following list briefly describes each printer-control function: 


Function - Description 
DeviceCapabilities Retrieves capabilities of a printer device driver. 
DeviceMode Sets the current printing modes for a device by 


prompting the user with a dialog box. 


ExtDeviceMode Retrieves or modifies device initialization informa- 
tion for a given printer driver or displays a driver- 
supplied dialog box for configuring the driver. 


2.16 Printer-Escape Function 


The Escape function allows an application to access facilities of a particular 
device that are not directly available through GDI. The nEscape parameter of this 
function specifies the escape function to be performed. When an application calls 
Escape for a printer device context, the escape functions regulate the flow of 
printer output from Windows applications, retrieve information about a printer, 
and alter the settings of a printer. 


2.16.1 Creating Output on a Printer 


Windows applications use only the standard Windows functions to access system 
memory, the output device, the keyboard, and the mouse. Each application inter- 
acts with the user through one or more windows that are created and maintained ° 
by the user. GDI assists an application in creating output by passing device-inde- 
pendent function calls from the application to the device driver. The device 
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driver first translates these device-independent function calls into device-depend- 
ent operations that create images on a device’s display surface, and then sends 
them to Print Manager (the spooler). Print Manager serves two purposes: it col- 
lects translated commands from one application and stores them in a correspond- 
ing job, and it passes a complete job to the device for output. Figure 2.20 shows 
the path of output from a Windows application to a device: 


Sn 


plcaton 


Say 


-O<-—--7~0 


Application |___, 
2 


Figure 2.20 Output Path 


If only one Windows application were allowed to run at any given time, Print 
Manager and many of the escape functions would be unnecessary. However, 
Windows allows several applications to run at once. If two or more of these appli- 
cations send output simultaneously, each applicaticn’s output must be separated 
and remain separated during printing or plotting. Print Manager maintains this 
separation. The printer-escape functions affect the way Print Manager handles 
this separation task. 


2.16.2 Banding Output 


The model used by GDI states that any point on an output device can be written 
to at any time. This model is easily implemented on vector devices but poses a 

' problem on many dot-matrix devices that cannot scroll backward. Banding pro- 
vides a solution to this problem. 


Banding involves several steps: 


1. The application creates a metafile and uses it as an intermediate storage 
device for the output. 
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2. Beginning at the top of the metafile, GDI translates a rectangular region 
(band) of output into device-specific commands, and then sends it to a corre- 
sponding job. 


3. The application repeats this process until the entire metafile has been con- 
verted to bands and the output from these bands has been translated into 
device-specific commands and stored in a job. 


4. The application sends the job to the output device. 


When creating a device context, GDI verifies whether the device has banding 
capabilities. If it does, GDI creates the metafile that will be used during the band- 
ing process. To implement banding, you call the necessary output functions and 
the NEXTBAND escape. The NEXTBAND escape requires a long pointer to a 
RECT data structure as its output parameter. The device driver copies the coordi- 
nates of the next band into this structure. When the entire metafile has been con- 
verted into device-specific commands, the driver returns four zeros (0,0,0,0) in 
the RECT structure. 


GDI does the banding for you if your output device has banding capabilities and 
you call the NEWFRAME escape. Although NEWFRAME requires moré 
memory and is slower, it does simplify the output process. After the application 
creates each page of output, it calls the NEWFRAME escape. If the device is 
capable of banding, GDI copies output to a metafile and calls the NEXTBAND 
escape for you. As discussed earlier, the NEXTBAND escape causes the con- 
tents of the metafile to be converted into device-specific commands and to be 
copied to a corresponding job. If a memory problem occurs or the user terminates 
a job, the NEWFRAME escape returns a message that defines the error or abort 
message. 


2.16.3 Starting and Ending a Print Job 


The STARTDOC escape informs the device driver that an application is begin- 
ning a new print job. After the STARTDOC call is issued, Print Manager queues 
all output from a particular application in a corresponding job until an ENDDOC 
escape is issued. (Note that you cannot use the ENDDOC escape to terminate a 
job.) 


2.16.4 Terminating a Print Job 


If you send output to a device with the NEWFRAME escape, you are required 
to write a termination procedure and supply it with the application. The SET- 
ABORTPROC escape sets a pointer to this procedure; it should be called prior 
to the STARTDOC escape. The ABORTDOC escape terminates print jobs if it 
is called before the first call to NEWFRAME. It should also be used to termi- 
nate jobs that use the NEXTBAND escape. 
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2.16.5 Information Escapes 


Four of the escape functions are used to retrieve information about the selected 
device and its settings. The GETPHYSPAGESIZE escape retrieves the physical 
page size of the output device (in device units), the smallest addressable units on 
the device. For example, one-fortieth of a millimeter is the smallest addressable 
unit on some vector devices. A pixel is the smallest addressable unit on a dot- 
matrix device. The GETPRINTINGOFFSET escape retrieves the distance (in 
device units) from the upper-left corner of the page to the point at which printing 
begins. The GETSCALINGFACTOR escape retrieves the scaling factors for 
the x- and y-axes of a device. The scaling factor expresses the number of logical 
units that are mapped to a device unit. The QUERYESCSUPPORT escape de- 
termines whether a particular escape function is implemented on a device driver. 
If the escape in question is implemented, QUERYESCSUPPORT returns a non- 
zero value. If the escape is not implemented, QUERYESCSUPPORT returns 
zero. 


2.16.6 Additional Escape Calls 


There are two additional escapes that alter the state of the device: the FLUSH- 
OUTPUT and DRAFTMODE escapes. The FLUSHOUTPUT escape flushes 
the output in the device’s buffer (the device stores device operations in the buffer 
before sending them to Print Manager). The DRAFTMODE escape turns on the 
device’s draft mode. This means that the device will use one of its own fonts in- 
stead of using a GDI font. It also means that calls to the text-justification func- 
tions that alter interword and intercharacter spacing are ignored. For a detailed 
description of the functions that alter interword and intercharacter spacing, see 
Sections 2.12, “Text Functions,” and 2.13, ‘Font Functions.” 


2.17 Environment Functions 


Environment functions alter and retrieve information about the environment as- 
sociated with an output device. The following list briefly describes the two en- 
viornment functions: 


Function Description 
GetEnvironment Copies environment information into a buffer. 
SetEnvironment Copies data to the environment associated with an at- 


tached device. 


2.18 Summary 
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Graphics device interface (GDI) functions perform device-independent graphics 
operations within a Windows application. For more information on topics related 
to GDI functions, see the following: 


Topic 

Function descriptions 
Windows data types and 
structures 

Metafile formats 

Raster operations 

Printer escapes 

Drawing text and graphics 
in a window 

Drawing bitmaps 


Sending output to a printer 


Text fonts 


Color palettes 


Reference . 


Reference, Volume 1: Chapter 4, “Functions 
Directory” 


Reference, Volume 2: Chapter 7, “Data Types 
and Structures” 


Reference, Volume 2: Chapter 9, “File 
Formats” 


Reference, Volume 2: Chapter 11, “Binary 
and Ternary Raster-Operation Codes” 


Reference, Volume 2: Chapter 12, “Printer 
Escapes” 


Guide to Programming: Chapter 3, “Output 
to a Window” 


Guide to Programming: Chapter 11, 
“Bitmaps” 


Guide to Programming: Chapter 12, 
“Printing,” and Chapter 17, “Print Settings” 


Guide to Programming: Chapter 18, “Fonts” 


Guide to Programming: Chapter 19, “Color 
Palettes” 


Chapter 


System Services Interface 
Functions 


This chapter describes the system services interface functions. These functions 
access code and data in modules, allocate and manage both local and global 
memory, manage tasks, load program resources, translate strings from one 
character set to another, alter the Microsoft Windows initialization file, assist in 
system debugging, carry out communications through the system’s I/O ports, 
create and open files, and create sounds using the system’s sound generator. 


This chapter lists the following categories of functions: 


= Module-management functions 
= Memory-management functions 
= Segment functions 

m Operating-system interrupt functions 
m Task functions 

= Resource-management functions 
= String-manipulation functions 

= Atom-management functions 

m Initialization-file functions 

= Communication functions 

= Sound functions 

= Utility macros and functions 

= File I/O functions 

= Debugging functions 

= Optimization-tool functions 


= Application-execution functions 
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3.1 Module-Management Functions 


Module-management functions alter and retrieve information about Windows 
modules, which are loadable, executable units of code and data. The following 
list briefly describes each module-management function: 


Function 


FreeLibrary 


FreeModule 


FreeProclInstance 


GetCodeHandle 
GetInstanceData | 


GetModuleFileName 
GetModuleHandle 
GetModuleUsage 
GetProcAddress 
GetVersion 
LoadLibrary 


MakeProclInstance 


Description 


Decreases the reference count of a library by one 
and removes it from memory if the reference count 
is Zero. 


Decreases the reference count of a module by one 
and removes it from memory if the reference count 
is Zero. 


Removes a function instance entry at an address. 


Determines which code segment contains a specified 
function. 


Copies data from an offset in one instance to an off- 
set in another instance. 


Copies a module filename. 

Returns the module handle of a module. 

Returns the reference count of a module. 
Returns the address of a function in a module. 
Returns the current version number of Windows. 
Loads a library module. | 


Returns a function-instance address. 


3.2 Memory-Management Functions 


Memory-management functions manage system memory. There are two catego- 
ries of functions: those that manage global memory and those that manage local 
memory. Global memory is all memory in the system that has not been allocated 
by an application or reserved by the system. Local memory is the memory within 
a Windows application’s data segment. The following list briefly describes each 
memory-management function: 


Function 


DefineHandleTable 
GetFreeSpace 
GetWinFlags 


GlobalAlloc 
GlobalCompact 
GlobalDiscard 
GlobalDosAlloc 
GlobalDosFree 
GlobalFlags 
GlobalFree 


GlobalHandle 
GlobalLock 


GlobalLRUNewest 
GlobalILRUOldest 


GlobalNotify 
GlobalReAlloc 
GlobalSize 
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Description 


Creates a private handle table in an application’s de- 
fault data segment. 


Retrieves the number of bytes available in the global 
heap. 


Retrieves information about the system memory con- 
figuration. 


Allocates memory from the global heap. 
Compacts global memory to generate free bytes. 


Discards a global memory block if the lock count is 
zero, but does not invalidate the handle of the 
memory block. 


Allocates global memory that can be accessed by 
DOS running in real or protected mode. 


Frees global memory previously allocated by the 
GlobalDosAlloc function. 


Returns the flags and lock count of a global memory 
block. 


Removes a global memory block and invalidates the 
handle of the memory block. 


Retrieves the handle of a global memory object. 


Retrieves a pointer to a global memory block 
specified by a handle. Except for nondiscardable ob- 
jects in protected (standard or 386 enhanced) mode, 
the block is locked into memory at the given address 
and its lock count is increased by one. 


Moves a global memory object to the newest least- 
recently-used (LRU) position. 


Moves a global memory object to the oldest least-re- 
cently-used (LRU) position. 


Installs a notification procedure for the current task. 
Reallocates a global memory block. 


Returns the size (in bytes) of a global memory block. 
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Function 


GlobalUnlock 


GlobalUnwire 


Global Wire 
LimitEMSPages 


LocalAlloc 
LocalCompact 


LocalDiscard 


LocalFlags 


LocalFree 


LocalHandle 
LocallInit 
LocalLock 


LocalReAlloc 
LocalShrink 
LocalSize 
LocalUnlock 
LockData 
LockSegment 
SetSwapAreaSize 


Description 


Invalidates the pointer to a global memory block pre- 
viously retrieved by the GlobalLock function. In 
real mode, or if the block is discardable, GlobalUn- 
lock decreases the block’s lock count by one. 


Decreases the lock count set by the GlobalWire 
function, and unlocks the memory block if the count 
is zero. 


Moves an object to low memory and increases the 
lock count. 


Limits the amount of expanded memory that 
Windows will assign to an application. 


Allocates memory from the local heap. 
Compacts local memory. 


Discards a local memory block if the lock count is 
zero, but does not invalidate the handle of the 
memory block. 


Returns the memory type of a local memory block. 


Frees a local memory block from memory if the lock 
count is zero and invalidates the handle of the 
memory block. 


Retrieves the handle of a local memory object. 
Initializes a local heap in the specified segment. 


Locks a block of local memory by increasing its 
lock count. 


Reallocates a local memory block. 

Shrinks the local heap. 

Returns the size (in bytes) of a local memory block. 
Unlocks a local memory block. 

Locks the current data segment in memory. 

Locks a specified data segment in memory. 


Increases the amount of memory that an application 
reserves for code segments. 
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Function 


SwitchStackBack 
SwitchStackTo 


UnlockData 
UnLockSegment 


3.3 Segment Functions 


Description 


Returns the stack of the current task to the task’s 
data segment after it had been previously redirected 
by the SwitchTasksBack function. 


Changes the stack of the current task to the specified 
data segment, such as the data segment of a dynamic- 
link library (DLL). 


Unlocks the current data segment. 


Unlocks a specified data segment. 


Segment functions allocate, free, and convert selectors; lock and unlock memory 
blocks referenced by selectors; and retrieve information about segments. The fol- 
lowing list briefly describes each selector function: 


Function 


AllocDStoCSAlias 


AllocSelector 


ChangeSelector 


DefineHandleTable 


FreeSelector 


GetCodelInfo 
GlobalFix 


Description 


Accepts a data-segment selector and returns a code- 
segment selector that can be used to execute code in 
a data segment. 


Allocates a new selector. 


Generates a temporary code selector that corre- 
sponds to a given data selector, or a temporary data 
selector that corresponds to a given code selector. 


Creates a private handle table which Windows up- 
dates automatically. 


Frees a selector originally allocated by the Alloc- 
Selector, AllocCStoDSAlias, or AllocDStoCS Alias 
functions. 


Retrieves information about a code segment. 


Prevents a global memory block from moving in 
linear memory. 
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Function Description 


GlobalPageLock Page-locks the memory associated with the specified 
global selector and increments its page-lock count. 
Memory that is page-locked cannot be moved or 
paged out to disk. 


GlobalPageUnlock Decrements the page-lock count for a block of 
memory. If the page-lock count reaches zero, the 
memory can be moved and paged out to disk. 


GlobalUnfix Unlocks a global memory block previously fixed by 
the GlobalF ix function. 

LockSegment Locks a segment in memory. 

UnlockSegment Unlocks a segment previously locked by the Lock- 
Segment function. 


NOTE Anapplication should not use these functions unless it is absolutely necessary. 
Use of these functions violates preferred Windows programming practices. 


3.4 Operating-System Interrupt Functions 


Operating-system interrupt functions allow an assembly-language application to 
perform certain DOS and NETBIOS interrupts without directly coding the inter- 
rupt. This ensures compatibility with future Microsoft products. 


The following list briefly describes these functions: 


Function Description 
DOS3Call Issues a DOS 21H (function-request) interrupt. 
NetBIOSCall Issues a NETBIOS 5CH interrupt. 


3.5 Task Functions 


Task functions alter the execution status of tasks, return information associated 
with a task, and retrieve information about the environment in which the task is 
executing. A task is a single Windows application call. The following list briefly 
describes each task function: 

Function Description 


Catch Copies the current execution environment to a buffer. 


ExitWindows Initiates the standard Windows shutdown procedure. 
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Function 


GetCurrentPDB 


GetCurrentTask 
GetDOSEnvironment 


GetNumTasks 


SetErrorMode 


Throw 


Yield 


Description 


Returns the current DOS Program Data Base (PDB), 
also known as the Program Segment Prefix (PSP). 


Returns the task handle of the current task. 


Retrieves the environment string of the currently run- 
ning task. 


Returns the number of tasks currently executing in 
the system. . 


Controls whether Windows handles DOS Function 
24H errors or allows the calling application to 
handle them. 


Restores the execution environment to the specified 
values. 


Halts the current task and starts any waiting task. 


3.6 Resource-Management Functions 


Resource-management functions find and load application resources from a 
* Windows executable file. A resource can be a cursor, icon, bitmap, string, or 
font. The following list briefly describes each resource-management function: 


Function 
AccessResource 
AllocResource 
FindResource 
FreeResource 
LoadAccelerators 
LoadBitmap 
LoadCursor 
LoadIcon 
LoadMenu 
LoadResource 
LoadString 


LockResource 


Description 

Opens the specified resource. 

Allocates uninitialized memory for a resource. 
Determines the location of a resource. 
Removes a loaded resource from memory. 
Loads an accelerator table. 

Loads a bitmap resource. 

Loads a cursor resource. 

Loads an icon resource. 

Loads a menu resource. 

Loads a resource. 

Loads a string resource. 


Retrieves the absolute memory address of a resource. 
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Function 
SetResourceHandler 
SizeofResource 


UnlockResource 


Description 
Sets up a function to load resources. 
Supplies the size (in bytes) of a resource. 


Unlocks a resource. 


3.7 String-Manipulation Functions 


String-manipulation functions translate strings from one character set to another, 
determine and convert the case of strings, determine whether a character is alpha- 
betic or alphanumeric, find adjacent characters in a string, and perform other 
string manipulation. The following list briefly describes each string-translation 


function: 


Function 
AnsiLower 
AnsiLowerBuff 
AnsiNext 


AnsiPrev 


AnsiToOem 
AnsiToOemBuff 


AnsiUpper 
AnsiUpperBuff 
IsCharAlpha 
IsCharAlphaNumeric 
IsCharLower 
IsCharUpper 

Istrcat 


Istremp 


Istrempi 


Description 
Converts a character string to lowercase. 
Converts a character string in a buffer to lowercase. 


Returns a long pointer to the next character in a 
string. 


Returns a long pointer to the previous character in a 
string. 


Converts an ANSI string to an OEM character string. 


Converts an ANSI string in a buffer to an OEM 
character string. 


Converts a character string to uppercase. 

Converts a character string in a buffer to uppercase. 
Determines whether a character is alphabetical. 
Determines whether a character is alphanumeric. 
Determines whether a character is lowercase. 
Determines whether a character is uppercase. 
Concatenates two strings identified by long pointers. 


Performs a case-sensitive comparison of two strings 
identified by long pointers. 


Performs a case-insensitive comparison of two 
strings identified by long pointers. 
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Function Description 

Istrepy Copies one string to another; both strings are iden- 
tified by long pointers. 

Istrlen Determines the length of a string identified by a long 
pointer. 

OemToAnsi Converts an OEM character string to an ANSI string. 

- OemToAnsiBuff Converts an OEM character string in a buffer to an 

ANSI string. 

ToAscii Translates a virtual-key code to the corresponding 
ANSI character or characters. 

wsprintf . Formats and stores a series of characters and values 
in a buffer. Format arguments are passed separately. 

wvysprintf Formats and stores a series of characters and values 
in a buffer. Format arguments are passed through an 
array. 


3.8 Atom-Management Functions 


Atom-management functions create and manipulate atoms. Atoms are integers 
that uniquely identify character strings. They are useful in applications that use 
many character strings and in applications that need to conserve memory. 
Windows stores atoms in atom tables. A local atom table is allocated in an appli- 
cation’s data segment; it cannot be accessed by other applications. The global 
atom table can be shared, and is useful in applications that use dynamic data ex- 
change (DDE). The following list briefly describes each atom-management func- 


tion: 

Function Description 

AddAtom _ Creates an atom for a character string. 

DeleteAtom Deletes an atom if the reference count is zero. 

FindAtom Retrieves an atom associated with a character string. 

GetAtomHandle Retrieves a handle (relative to the local heap) of the 
string that corresponds to a specified atom. 

GetAtomName Copies the character string associated with an atom. 

GlobalAddAtom Creates a global atom for a character string. 


GlobalDeleteAtom Deletes a global atom if the reference count is zero. 


3-10 Reference — Volume 1 


Function Description 

GlobalFindAtom Retrieves a global atom associated with a character 
string. 

GlobalGetAtomName Copies the character string associated with a global 
atom. 

InitAtomTable Initializes an atom hash table. 

MAKEINTATOM Casts an integer for use as a function argument. 


3.9 Initialization-File Functions 


Initialization-file functions obtain information from and copy information to the 
Windows initialization file WIN.INI and private initialization files. A Windows 
initialization file is a special ASCII file that contains key-name—value pairs that 
represent run-time options for applications. The following list briefly describes 
each initialization-file function: 


Function Description 

GetPrivateProfileInt Returns an integer value in a section 
from a private initialization file. 

GetPrivateProfileString Returns a character string in a section 
from a private initialization file. 

GetProfileInt Returns an integer value in a section 
from the WIN.INI file. 

GetProfileString Returns a character string in a section 
from the WIN.INI file. 

WritePrivateProfileString Copies a character string to a private 


initialization file, or deletes one or 
more lines in a private initialization 
file. 


WriteProfileString Copies a character string to the. 
WIN.INI file, or deletes one or more 
lines from WIN.INI. 


An application should use a private (application-specific) initialization file to re- 
cord information which affects only that application. This improves both the per- 
formance of the application and Windows itself by reducing the amount of 
information that Windows must read when it accesses the initialization file. An 
application should record information in WIN.INI only if it affects the Windows 
environment or other applications; in such cases, the application should send the 
WM_WININICHANGE message to all top-level windows. 
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The files WININI.TXT and SYSINI.TXT supplied with the retail version of 
Windows describe the contents of WIN.INI and SYSTEM.INI, respectively. 


3.10 Communication Functions 


Communication functions carry out communications through the system’s serial 
and parallel I/O ports. The following list briefly describes each communication 


function: 


Function 
BuildCommDCB 


ClearCommBreak 
CloseComm 


EscapeCommFunction 
FlushComm 
GetCommError 
GetCommEventMask 
GetCommState 
OpenComm 


ReadComm 


SetCommBreak 


SetCommEventMask 
SetCommState 


TransmitCommChar 


UngetCommChar 


WriteComm 


Description 


Fills a device control block with control codes. 


Clears the communication break state from a com- 
munication device. 


Closes a communication device after transmitting 
the current buffer. . 


Directs a device to carry out an extended function. 
Flushes characters from a communication device. 
Fills a buffer with the communication status. 
Retrieves, then clears, an event mask. 

Fills a buffer with a device control block. 

Opens a communication device. | 


Reads the bytes from a communication device into a 
buffer. 


Sets a break state on the communication device. 


Retrieves and then sets an event mask on the com- 
munication device. 


Sets a communication device to the state specified 
by the device control block. 


Places a character at the head of the transmit queue. 


Specifies which character will be the next character 
to be read. 


Writes the bytes from a buffer to a communication 
device. 
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3.11 Sound Functions 


Sound functions create sound and music for the system’s sound generator. The 
following list briefly describes each sound function: 


Function 


CloseSound 


CountVoiceNotes 
GetThresholdEvent 
GetThresholdStatus 
OpenSound 
SetSoundNoise 


Set VoiceAccent 
Set VoiceEnvelope 
Set VoiceNote 


Set VoiceQueueSize 
Set VoiceSound 


Set VoiceThreshold 
StartSound 
StopSound 


SyncAllVoices 
WaitSoundState 


Description 


Closes the play device after flushing the voice 
queues and freeing the buffers. 


Returns the number of notes in the specified queue. 
Returns a long pointer to a threshold flag. 

Returns the threshold-event status for each voice. 
Opens the play device for exclusive use. 


Sets the source and duration of a noise from the play 
device. 


Places an accent in the voice queue. 
Places the voice envelope in the voice queue. 
Places a note in the specified voice queue. 


Allocates a specified number of bytes for the voice 
queue. 


Places the specified sound frequency and durations 
in a voice queue. 


Sets the threshold level for a given voice. 
Starts playing each voice queue. 


Stops playing all voice queues and flushes their con- 
tents. 


Places a sync mark in each voice queue. 


Waits until the play driver enters the specified state. 


3.12 Utility Macros and Functions 


Utility macros and functions return contents of words and bytes, create unsigned 
long integers and data structures, and perform specialized arithmetic. The follow- 
ing list briefly describes each utility macro or function: 
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Function 

HIBYTE 

HIWORD 

LOBYTE 

LOWORD 
MAKEINTATOM 
MAKEINTRESOURCE 


MAKELONG 
MAKEPOINT 


MulDiv 


PALETTEINDEX 
PALETTERGB 


RGB 


3.13 File I/O Functions 


Description 

Returns the high-order byte of an integer. 
Returns the high-order word of a long integer. 
Returns the low-order byte of an integer. 
Returns the low-order word of a long integer. 
Casts an integer for use as a function argument. 


Converts an integer value into a long pointer to a 
string, with the high-order word of the long pointer 
set to zero. 


Creates an unsigned long integer. 


Converts a long value that contains the x- and y- 
coordinates of a point into a POINT data structure. 


Multiplies two word-length values and then divides 
the result by a third word-length value, returning the 
result rounded to the nearest integer. 


Converts an integer into a palette-index 
COLORREF value. 


Converts three values for red, green, and blue into a 
palette-relative RGB COLORREF value. 


Converts three values for red, green, and blue into 
an explicit RGB COLORREF value. 


File I/O functions create, open, read from, write to, and close files. The following 
list briefly describes each file I/O function: 


Function 


GetDriveType 
GetSystemDirectory 
GetTempDrive 


GetTempFileName 
GetWindowsDirectory 


Description 


Determines whether a disk drive is removeable, 
fixed, or remote. 


Retrieves the pathname of the Windows system sub- 
directory. 


Returns the letter of the optimal drive for temporary 
file storage. 


Creates a temporary filename. 


Retrieves the pathname of the Windows directory. 
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Function Description 

_Iclose Closes a file. 

_Icreat Creates a new file or opens and truncates an existing 
file. 

_llseek Positions the pointer to a file. 

_lopen Opens an existing file. 

_lread Reads data from a file. 

_Iwrite Writes data in a file. 

OpenFile Creates, opens, reopens, or deletes the specified file. 

SetHandleCount ei the number of file handles available to a 
task. 


3.14 Debugging Functions 


Debugging functions help locate programming errors in an application or library. 
The following briefly describes these functions: 


Function Description 

DebugBreak Forces a break to the debugger. 

FatalAppExit Displays a message box and then terminates the 
application. 

FatalExit Displays the current state of Windows and prompts 
for instructions on how to proceed. 

OutputDebugString Sends a debugging message to the debugger if pre- 
sent, or to the AUX device if the debugger is not pre- 
sent. 


ValidateCodeSegments Determines whether any code segments have been 
altered by random memory overwrites. 


ValidateFreeSpaces Checks free segments in memory for valid contents. 


3.15 Optimization-Tool Functions 


Optimization-tool functions control how the Windows Profiler and Swap soft- 
ware development tools interact with an application being developed. The follow- 
ing list briefly describes these functions: 
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Function Description 

ProfClear Discards all samples in the Profiler sampling buffer. 

ProfFinish Stops sampling by Profiler and flushes the buffer to 
disk. 

ProfF lush Flushes the Profiler sampling buffer to disk. 

ProfInsChk Determines if Profiler is installed. 

ProfSampRate Sets the rate of code sampling by Profiler. 

ProfSetup Sets up the Profiler sampling buffer and recording 
rate. 

ProfStart Starts sampling by Profiler. 

ProfStop Stops sampling by Profiler. 

SwapRecording Begins or ends analyzing by Swap of the applica- 


tion’s swapping behavior. 


3.16 Application-Execution Functions 


Application-execution tasks permit one application to execute another program. 
The following list briefly describe these functions: 


Function Description 

LoadModule Executes a separate application. 

WinExec Executes a separate application. 

WinHelp Runs the Windows Help application and passes con- 


text or topic information to Help. 


The WinExec function provides a high-level method for executing any Windows 
or standard DOS application. The calling application supplies a string containing 
the name of the executable file to be run and any command parameters, and 
specifies the initial state of the application’s window. 


The LoadModule function is similar, but provides more control over the environ- 
ment in which the application is executed. The calling application supplies the 
name of the executable file and a DOS Function 4BH, Code 00H, parameter 
block. 


The WinHelp function executes the Windows Help application and optionally 
passes data to it indicating the nature of the help requested by the application. 
This data is either an integer which specifies a context identifier in the help file 
or a string containing a key word in the help file. 


3.17 Summary 
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System services interface functions access code and data in modules, allocate and 
manage both local and global memory, manage tasks, load program 

resources, translate strings from one character set to another, alter the Windows 
initialization file, assist in system debugging, carry out communications through 
the system’s I/O ports, create and open files, and create sounds using the sys- 
tem’s sound generator. For more information on topics related to system services 
interface functions, see the following: 


Topic 

Function descriptions 
Windows data types and 
structures 
Initialization-file formats 
Diagnostic messages for 
debugging 


Writing and reading from 
files . 


Managing memory 
_ Libraries 
Using Profiler 


Using Swap 


Reference 


Reference, Volume 1: Chapter 4, “Functions 
Directory” 


Reference, Volume 2: Chapter 7, “Data Types 
and Structures” 


Reference, Volume 2: Chapter 9, “File 


Formats” 


Reference, Volume 2: Appendix C, 
“Windows Debugging Messages” 


Guide to Programming: Chapter 10, “File 
Input and Output” . 


Guide to Programming: Chapter 15, 
“Memory Management,” and Chapter 16, 


“More Memory Management” 


Guide to Programming: Chapter 20, 
“Dynamic-Link Libraries” 


Tools: Chapter 13, “Analyzing CPU Time: 
Profiler” 


Tools: Chapter 14, “Analyzing Swaps: Swap” 


Chapter 


Functions Directory 


This chapter contains an alphabetical list of functions from the Microsoft 
Windows application programming interface (API). The documentation for each 
function contains a line illustrating correct syntax, a statement about the func- 
tion’s purpose, a description of its input parameters, and a description of its re- 
turn value. The documentation for some functions contains additional, important 
information that an application developer needs in order to use the function. 
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_ AccessResource 


Syntax 


Return Value 


Comments 


AddAtom 
Syntax 


int AccessResource(//nstance, hResInfo) 


This function opens the specified resource file and moves the file pointer to the begin- 
ning of the specified resource, letting an application read the resource from the file. The 
AccessResource function supplies a DOS file handle that can be used in subsequent file- 
read calls to load the resource. The file is opened for reading only. 


Applications that use this function must close the resource file by calling the _Iclose func- 
tion after reading the resource. 


Parameter Type/Description 

hiInstance HANDLE Identifies the instance of the module whose exe- 
cutable file contains the resource. 

hResInfo HANDLE Identifies the desired resource. This handle should 


be created by using the FindResource function. 


The return value specifies a DOS file handle to the designated resource file. It is —1 if the 
resource cannot be found. 


AccessResource can exhaust available DOS file handles and cause errors if the opened 
file is not closed after the resource.is accessed. 


ATOM = AddAtom(ipString) 


This function adds the character string pointed to by the /pString parameter to the atom 
table and creates a new atom that uniquely identifies the string. The atom can be used in a 
subsequent GetAtomName function to retrieve the string from the atom table. 


The AddAtom function stores no more than one copy of a given string in the atom table. If 
the string is already in the table, the function returns the existing atom value and increases 
the string’s reference count by one. 


Parameter Type/Description 


IpString LPSTR Points to the character string to be added to the table. 
The string must be a null-terminated character string. 
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AddFontResource 


Return Value 


The return value specifies the newly created atom if the function is successful. Otherwise, 
it is NULL. 


Comments The atom values returned by AddAtom range from 0xCO000 to OxFFFF. Atoms are case in- 
sensitive. 

AddFontResource 

Syntax int AddFontResource(/pFilename) 


Return Value 


Comments 


This function adds the font resource from the file named by the /pFilename parameter to 
the Windows font table. The font can subsequently be used by any application. 


Parameter Type/Description 


IpFilename LPSTR Points to a character string that names the font- 

| resource file or contains a handle to a loaded module. If 
IpFilename points to the font-resource filename, the string must 
be null-terminated, have the DOS filename format, and include 
the extension. If /pFilename contains a handle, the handle is in 
the low-order word and the high-order word is zero. 


The return value specifies the number of fonts added. The return value is zero if no fonts 
are loaded. 


Any application that adds or removes fonts from the Windows font table should notify 
other windows of the change by using the SendMessage function with the hWnd parame- 
ter set to—1 to send a WM_FONTCHANGE message to all top-level windows in the sys- 
tem. 


It is good practice to remove any font resource an application has added once the applica- 
tion is through with the resource. 


For a description of font resources, see the Guide to Programming. 


AdjustWindowRect 


Syntax 


void AdjustWindowRect(/pRect, dwStyle, bMenu) 


This function computes the required size of the window rectangle based on the desired 
client-rectangle size. The window rectangle can then be passed to the CreateWindow 
function to create a window whose client area is the desired size. A client rectangle is the 
smallest rectangle that completely encloses a client area. A window rectangle is the 
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Return Value 


Comments 


smallest rectangle that completely encloses the window. The dimensions of the resulting 
window rectangle depend on the window styles and on whether the window has a menu. 


Parameter Type/Description 

IpRect LPRECT Points toa RECT data structure that contains the 
coordinates of the client rectangle. 

dwStyle DWORD _ Specifies the window styles of the window whose 
client rectangle is to be converted. 

bMenu BOOL Specifies whether the window has a menu. 

None. 


This function assumes a single menu row. If the menu bar wraps to two or more rows, the 
coordinates are incorrect. 


AdjustWindowRectEx 


Syntax 


void AdjustWindowRectEx(lpRect, dwStyle, bMenu, dwExStyle) 


This function computes the required size of the rectangle of a window with extended style 
based on the desired client-rectangle size. The window rectangle can then be passed to the 
Create WindowEx function to create a window whose client area is the desired size. 


A client rectangle is the smallest rectangle that completely encloses a client area. A 
window rectangle is the smallest rectangle that completely encloses the window. The 
dimensions of the resulting window rectangle depends on the window styles and on 
whether the window has a menu. 


Parameter Type/Description 

IpRect LPRECT Points to a RECT data structure that contains the 
coordinates of the client rectangle. 

dwStyle DWORD Specifies the window styles of the window whose 
client rectangle is to be converted. 

bMenu BOOL Specifies whether the window has a menu. 

dwExStyle DWORD Specifies the extended style of the window being 


created. 
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AllocDStoCSAlias 


Return Value 


Comments 


None. 


This function assumes a single menu row. If the menu bar wraps to two or more rows, the 
coordinates are incorrect. 


AllocDStoCSAlias 


Syntax 


Return Value 


Comments 


AllocResource 
Syntax 


WORD AllocDStoCSAlias(wSelector) 


This function accepts a data-segment selector and returns a code-segment selector that can 
be used to execute code in the data segment. When in protected mode, attempting to exe- 
cute code directly in a data segment will cause a general protection violation. Alloc- 
DStoCSAlias allows an application to execute code which the application had created in 
its own stack segment. 


The application must free the new selector by calling the FreeSelector function. 


Parameter Type/Description 


wSelector WORD Specifies the data-segment selector. 


The return value is the code-segment selector corresponding to the data-segment Seleclon 
If the function cannot allocate a new selector, the return value is zero. 


Windows does not track segment movements. Consequently, the data segment must be 
fixed and nondiscardable; otherwise, the data segment might move, invalidating the code- 
segment selector. 


The ChangeSelector function provides another method of obtaining a code selector corre- 
sponding to a data selector. 


An application should not use this function unless it is absolutely necessary. Use of this 
function violates preferred Windows programming practices. 


HANDLE §AllocResource(//nstance, hResInfo, dwSize) 


This function allocates uninitialized memory for the passed resource. All resources must 
be initially allocated by using the AllocResource function. The LoadResource function 
calls this function before loading the resource. 
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Return Value 


Parameter Type/Description 


hInstance HANDLE Identifies the instance of the module whose exe- 
cutable file contains the resource. 


hResInfo HANDLE _ Identifies the desired resource. It is assumed that 
this handle was created by using the FindResource function. 


dwSize DWORD _ Specifies an override size in bytes to allocate for 
the resource. The override is ignored if the size is zero. 


The return value identifies the global memory block allocated for the resource. 


AllocSelector 


Syntax 


Return Value 


Comments 


WORD AllocSelector(wSelector) 


This function allocates a new selector. If the wSelector parameter is a valid selector, Alloc- 
Selector returns a new selector which is an exact copy of the one specified by wSelector. 
If wSelector is NULL, AllocSelector returns a new, uninitialized selector. 


The application must free the new selector by calling the FreeSelector function. 


Parameter Type/Description 


wSelector WORD _ Specifies the selector to be copied, or NULL if Alloc- 
Selector is to allocate a new, uninitialized selector. 


The return value is either a selector that is a copy of an existing selector, or a new, uninitial- 
ized selector. If the function could not allocate a new selector, the return value is zero. 


An application can call AllocSelector to allocate a selector that it can pass to the Change- 
Selector function. 


An application should not use this function unless it is absolutely necessary. Use of this 
function violates preferred Windows programming practices. 
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AnimatePalette 
Syntax void AnimatePalette()Palette, wStartIndex, wNumEntries, lpPaletteColors) 


This function replaces entries in the logical palette identified by the /Palette parameter. 
When an application calls AnimatePalette, it does not have to update its client area be- 
cause Windows maps the new entries into the system palette immediately. | 


Parameter Type/Description 

hPalette HPALETTE Identifies the logical palette. 

wStartIndex WORD Specifies the first entry in the palette to be animated. 

wNumEntries WORD _ Specifies the number of entries in the palette to be an- 
imated. 

IpPaletteColors LPPALETTEENTRY Points to the first member of an array 


of PALETTEENTRY data structures to replace the palette en- 
tries identified by wStartIndex and wNumEntries. 


Return Value None. 


Comments AnimatePalette will only change entries with the PC_RESERVED flag set in the corre- 
sponding palPaletteEntry field of the LOGPALETTE data structure that defines the cur- 
rent logical palette. The CreatePalette function creates a logical palette. 


AnsiLower 
Syntax LPSTR = AnsiLower(/pString) 


This function converts the given character string to lowercase. The conversion is made by 
the language driver based on the criteria of the current language selected by the user at 
setup or with the Control Panel. 


Parameter Type/Description 


IpString LPSTR Points to a null-terminated character string or speci- 
fies single character. If [pString specifies single character, that 
character is in the low-order byte of the low-order word, and the 
high-order word is zero. 


A— 
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Return Value 


The return value points to a converted character string if the function parameter is a 
character string. Otherwise, it is a 32-bit value that contains the converted character in the 
low-order byte of the low-order word. 


AnsiLowerBuff 


Syntax 


Return Value 


AnsiNext 
Syntax 


Return Value 


Comments” 


WORD AnsiLowerBuff(/pString, nLength) 


This function converts character string in a buffer to lowercase. The conversion is made by 
the language driver based on the criteria of the current language selected by the user at 
setup or with the Control Panel. 


Parameter Type/Description 

IpString LPSTR Points to a buffer containing one or more characters. 

nLength WORD Specifies the number of characters in the buffer iden- 
tified by the /pString parameter. If nLength is zero, the length is 
64K (65,536). 


The return value specifies the length of the converted string. 


LPSTR = AnsiNext(/pCurrentChar) 


This function moves to the next character in a string. 


Parameter | Type/Description 


IpCurrentChar LPSTR Points to a character in a null-terminated string. 


The return value points to the next character in the string, or, if there is no next character, 
to the null character at the end of the string. 


The AnsiNext function is used to move through strings whose characters are two or more 
bytes each (for example, strings that contain characters from a Japanese character set). 
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AnsiPrev 


AnsiPrev 
Syntax 


Return Value 


Comments 


AnsiToO0em 
Syntax 


Return Value 


LPSTR = AnsiPrev(/pStart, I|pCurrentChar) 


This function moves to the previous character in a string. 


Parameter Type/Description 
IpStart LPSTR Points to the beginning of the string. 
IpCurrentChar LPSTR Points to a character in a null-terminated string. 


The return value points to the previous character in the string, or to the first character in 
the string if the JpCurrentChar parameter is equal to the /pStart parameter. 


The AnsiPrev function is used to move through strings whose characters are two or more 
bytes each (for example, strings that contain characters from a Japanese character set). 


int AnsiToOem(/pAnsiStr, lpOemStr) 


This function translates the string pointed to by the /pAnsiStr parameter from the ANSI 
character set into the OEM-defined character set. The string can be greater than 64K in 
length. 


Parameter Type/Description 

IpAnsiStr LPSTR Points to a null-terminated string of characters from 
the ANSI character set. 

lpOemStr LPSTR Points to the location where the translated string is to 


be copied. The JpOemStr parameter can be the same as /pAnsiStr 
to translate the string in place. 


The return value is always —1. 


AnsifoOemBuff 
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Syntax 


Return Value 


AnsiUpper 
Syntax 


Return Value 


_ AnsiToOemBuft 


void AnsiToOemBuff(/pAnsiStr, lpOemStr, nLength) 


This function translates the string in the buffer pointed to by the /pAnsiStr parameter from 
the ANSI character set into the OEM-defined character set. 


Parameter 


[pAnsiStr 


lpOemStr 


nLength 


None. 


Type/Description 


LPSTR Points to a buffer containing one or more characters 
from the ANSI character set. 


LPSTR Points to the location where the translated string is to 
be copied. The /pOemStr parameter can be the same as /pAnsiStr 
to translate the string in place. 


WORD _ Specifies the number of characters in the buffer iden- 
tified by the /pAnsiStr parameter. If nLength is zero, the length is 
64K (65,536). 


LPSTR AnsiUpper(/pString) 


This function converts the given character string to uppercase. The conversion is made by 
the language driver based on the criteria of the current language selected by the user at 
setup or with the Control Panel. 


Parameter 


lpString 


Type/Description 


LPSTR Points to a null-terminated character string or speci- 
fies single character. If JpString specifies a single character, that 
character is in the low-order byte of the low-order word, and the 
high-order word is zero. 


The return value points to a converted character string if the function parameter is a 
character string; otherwise, it is a 32-bit value that contains the converted character in the 
low-order byte of the low-order word. 


4-11 AnsiUpperButf 


AnsiUpperBuff 
Syntax WORD AnsiUpperBuff(/pString, nLength) 


This function converts a character string in a buffer to uppercase. The conversion is made 
by the language driver based on the criteria of the current language selected by the user at 
setup or with the Control Panel. 


Parameter Type/Description 
IpString LPSTR Points to a buffer containing one or more characters. 


nLength WORD _ Specifies the number of characters in the buffer iden- 
tified by the /pString parameter. If nLength is zero, the length is 
64K (65,536). 


Return Value The return value specifies the length of the converted string. 


AnyPopup 
Syntax BOOL AnyPopup( ) 


This function indicates whether a pop-up window exists on the screen. It searches the en- 
tire Windows screen, not just the caller’s client area. The AnyPopup function returns non- 
zero even if a pop-up window is completely covered by another window. 


This function has no parameters. 


Return Value The return value is nonzero if a pop-up window exists. Otherwise, it is zero. 


AppendMenu 
Syntax BOOL AppendMenu(hMenu, wFlags, wIDNewItem, lpNewltem) 


This function appends a new item to the end of a menu. The application can specify the 
state of the menu item by setting values in the wFlags parameter. 


AppendMenu 


Return Value — 


Comments 


Parameter 
hMenu 
wF lags 


wlDNewltem 


IpNewltem 
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Type/Description 
HMENU Identifies the menu to be changed. 


WORD Specifies information about the state of the new 
menu item when it is added to the menu. It consists of one or 
more values listed in the following “Comments” section. 


WORD Specifies either the command ID of the new menu 
item or, if wFlags is set to MF_POPUP, the menu handle of 
the pop-up menu. 


LPSTR Specifies the content of the new menu item. The 
interpretation of the JpNew/tem parameter depends upon the 
setting of the wFlags parameter. 


If wFlags is IpNewlItem 


MF_STRING Contains a long pointer to a null- 
terminated character string. 


MF_BITMAP Contains a bitmap handle HBIT- 
MAP in its low-order word. 


MF_OWNERDRAW Contains an application-supplied 
32-bit value which the application 
can use to maintain additional data 
associated with the menu item. 
This 32-bit value is available to 
the application in the itemData 
field of the structure pointed to by 
the /Param parameter of the 
WM_MEASUREITEM and 
WM_DRAWITEM messages sent 
when the menu item is initially dis- 
played or is changed. 


The return value specifies the outcome of the function. It is TRUE if the function is 
successful. Otherwise, it is FALSE. 


Whenever a menu changes (whether or not the menu resides in a window that is dis- 
played), the application should call DrawMenuBar. . 


Each of the following groups lists flags that are mutually exclusive and should not be used 


together: 
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AppendMenu 


= MF_BYCOMMAND and MF_BYPOSITION 

=» MF_DISABLED, MF_ENABLED, and MF_GRAYED 
= MF _BITMAP, MF_STRING, and MF_WNERDRAW 
m= MF_MENUBARBREAK and MF_MENUBREAK 

™ MF_CHECKED and MF_UNCHECKED 


The following list describes the flags which may be set in the wF/ags parameter: 


Value Meaning 


MF_BITMAP Uses a bitmap as the item. The low-order word of the 
IpNewItem parameter contains the handle of the bitmap. 


MF_CHECKED Places a checkmark next to the item. If the application 
has supplied checkmark bitmaps (see SetMenultemBit- 
maps), setting this flag displays the “checkmark on” 
bitmap next to the menu item. 


MF_DISABLED Disables the menu item so that it cannot be selected, but 
does not gray it. 

MF_ENABLED Enables the menu item so that it can be selected and re- 
stores it from its grayed state. 

MF_GRAYED Disables the menu item so that it cannot be selected and 
grays it. 


MF_MENUBARBREAK Same as MF_MENUBREAK except that for pop-up 
menus, separates the new column from the old column 
with a vertical line. 


MF_MENUBREAK Places the item on a new line for static menu-bar items. 
For pop-up menus, places the item in a new column, 
with no dividing line between the columns. 


MF_OWNERDRAW Specifies that the item is an owner-draw item. The 
window that owns the menu receives a 
WM_MEASUREITEM message when the menu is dis- 
played for the first time to retrieve the height and width 
of the menu item. The WM_DRAWITEM message is 
then sent whenever the owner must update the visual ap- 
pearance of the menu item. This option is not valid for a 
top-level menu item. 


-Vv 


Arc 
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Arc 
Syntax 


Value 


MF_POPUP 


MF_SEPARATOR 


MF_STRING 


MF_UNCHECKED 


Meaning 


Specifies that the menu item has a pop-up menu as- 
sociated with it. The w/DNewI/tem parameter specifies a 
handle to a pop-up menu to be associated with the item. 
This is used for adding either a top-level pop-up menu or 
adding a hierarchical pop-up menu to a pop-up menu 
item. 


Draws a horizontal dividing line. Can only be used ina 
pop-up menu. This line cannot be grayed, disabled, or 
highlighted. The /pNew/tem and wIDNewItem parame- 
ters are ignored. 


Specifies that the menu item is a character string; the 
IpNewItem parameter points to the string for the menu 
item. 


Does not place a checkmark next to the item (default). If 

the application has supplied checkmark bitmaps (see Set- 
- MenultemBitmaps), setting this flag displays the 

“checkmark off” bitmap next to the menu item. 


BOOL § Are(ADC, X/, Y1, X2, ¥2, X3, Y3, X4, Y4) 


This function draws an elliptical arc. The center of the arc is the center of the bounding 
rectangle specified by the points (X/, Y/) and (X2, Y2). The arc starts at the point (X3, Y3) 
and ends at the point (X4, Y4). The arc is drawn using the selected pen and moving ina 
counterclockwise direction. Since an arc does not define a closed area, it is not filled. 


Parameter 
hDC 
Xl 


Yl 


X2 


Type/Description 
HDC _ Identifies the device context. 


int Specifies the logical x-coordinate of the upper-left corner 
of the bounding rectangle. 


int Specifies the logical y-coordinate of the upper-left corner 
of the bounding rectangle. 


int Specifies the logical x-coordinate of the lower-right corner 
of the bounding rectangle. 


ArrangelconicWindow 


Return Value 


Comments 


Parameter Type/Description 


Y2 int Specifies the logical y-coordinate of the lower-right corner 
of the bounding rectangle. 


X3 int Specifies the logical .-coordinate of the arc’s starting 
point. This point does not have to lie exactly on the arc. 


Y3 int Specifies the logical y-coordinate of the arc’s starting 
point. This point does not have to lie exactly on the arc. 


X4 int Specifies the logical x-coordinate of the arc’s endpoint. 
This point does not have to lie exactly on the arc. 


Y4 int Specifies the logical y-coordinate of the arc’s endpoint. 
This point does not have to lie exactly on the arc. 


The return value specifies whether the arc is drawn. It is nonzero if the arc is drawn. Other- 
wise, it iS zero. 


The width of the rectangle specified by the absolute value of X2 — X/] must not exceed. 
32,767 units. This limit applies to the height of the rectangle as well. 


ArrangelconicWindows 


Syntax 


Return Value 


Comments — 


WORD ArrangelconicWindows(hWnd) 


This function arranges all the minimized (iconic) child windows of the window specified 
by the hWnd parameter. 


Parameter Type/Description 


hWnd HWND Identifies the window. 


The return value is the height of one row of icons, or zero if there were no icons. 


Applications that maintain their own iconic child windows call this function to arrange 
icons in a client window. This function also arranges icons on the desktop window, which 
covers the entire screen. The GetDesktop Window function retrieves the window handle 
of the desktop window. 


To arrange iconic MDI child windows in an MDI client window, an application sends the 
WM_MDIICONARRANGE message to the MDI client window. 
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BeginDeferWindowPos 


Syntax 


Return Value 


- BeginPaint 
Syntax | 


HANDLE BeginDeferWindowPos(nNumWindows) 


This function allocates memory to contain a multiple window-position data structure and 
returns a handle to the structure. The Defer WindowPos function fills this data structure 
with information about the target position for a window that is about to be moved. The 
EndDefer WindowPos function accepts this data structure and instantaneously repositions 
the windows using the information stored in the structure. 


Parameter Type/Description 


nNumWindows int Specifies the initial number of windows for which position 
information is to be stored in the data structure. The Defer- 
WindowPos function increases the size of the structure if 
needed. 


The return value identifies the multiple window-position data structure. The return value is 
NULL if system resources are not available to allocate the structure. 


HDC BeginPaint(Wnd, IpPaint) 


This function prepares the given window for painting and fills the paint structure pointed 
to by the /pPaint parameter with information about the painting. 


The paint structure contains a handle to the device context for the window, a RECT data 
structure that contains the smallest rectangle that completely encloses the update region, 
and a flag that specifies whether or not the background has been erased. 


The BeginPaint function automatically sets the clipping region of the device context to ex- 
clude any area outside the update region. The update region is set by the InvalidateRect or 
InvalidateRgn functions and by the system after sizing, moving, creating, scrolling, or 
any other operation that affects the client area. If the update region is marked for erasing, 
BeginPaint sends a WM_ERASEBKGND message to the window. 


An application should not call the BeginPaint function except in response to a 
WM_PAINT message. Each BeginPaint call must have a matching call to the EndPaint 
function. 


BitBit 


Return Value 


Comments 


BitBit 
Syntax 


Parameter 


hWnd 
IpPaint 


Type/Description 
HWND Identifies the window to be repainted. 


LPPAINTSTRUCT Points to the PAINTSTRUCT data structure 
that is to receive painting information, such as the device context for 
the window and the update rectangle. 


The return value identifies the device context for the specified window. 


If the caret is in the area to be painted, the BeginPaint function automatically hides the 
caret to prevent it from being erased. 


BOOL _ BitBlt(DestDC, X, Y, nWidth, nHeight, hSrcDC, XSrc, YSrc, dwRop) 


This function moves a bitmap from the source device given by the hSrcDC parameter to 
the destination device given by the hDestDC parameter. The XSrc and YSrc parameters 
specify the origin on the source device of the bitmap that is to be moved. The X, Y, nWidth, 
and nHeight parameters specify the origin, width, and height of the rectangle on the desti- 
nation device that is to be filled by the bitmap. The dwRop parameter (raster operation) de- 
fines how the bits of the source and destination are combined. 


Parameter 


hDestDC 
xX 


nWidth 


nHeight 


hSrcDC 


Type/Description 
HDC Identifies the device context that is to receive the bitmap. 


int Specifies the logical x-coordinate of the upper-left corner of the 
destination rectangle. 


int Specifies the logical y-coordinate of the upper-left corner of the 
destination rectangle. 


int Specifies the width (in logical units) of the destination 
rectangle and source bitmap. 


int Specifies the height (in logical units) of the destination 
rectangle and source bitmap. 


HDC Identifies the device context from which the bitmap will be 
copied. It must be NULL if the dwRop parameter specifies a raster 
operation that does not include a source. 


BitBit 4-18 
Parameter Type/Description 
XSrc int Specifies the logical x-coordinate of the upper-left corner of the 
source bitmap. 
YSre int Specifies the logical y-coordinate of the upper-left corner of the 


Return Value 


Comments 


source bitmap. 


dwRop DWORD _ Specifies the raster operation to be performed. Raster- 
operation codes define how the graphics device interface (GDI) 
combines colors in output operations that involve a current brush, a 
possible source bitmap, and a destination bitmap. For a list of raster- 
operation codes, see Table 4.1, “Raster Operations.” 


The return value specifies whether the bitmap is drawn. It is nonzero if the bitmap is 
drawn. Otherwise, it is zero. 


GDI transforms the nWidth and nHeight parameters, once by using the destination display 
context, and once by using the source display context. If the resulting extents do not 

match, GDI uses the StretchBlt function to compress or stretch the source bitmap as neces- 
sary. If destination, source, and pattern bitmaps do not have the same color format, the 
BitBlt function converts the source and pattern bitmaps to match the destination. The fore- 
ground and background colors of the destination are used in the conversion. 


If BitBIt converts monochrome bitmaps to color, it sets white bits (1) to the background 
color and black bits (0) to the foreground color. The foreground and background colors of 
the destination device context are used. To convert color to monochrome, BitBIt sets pix- 
els that match the background color to white (1), and sets all other pixels to black (0). The 
foreground and background colors of the color-source device context are used. 


The foreground color is the current text color for the specified device context, and the 
background color is the current background color for the specified device context. 


Not all devices support the BitBlt function. For more information, see the RC_BITBLT 
raster capability in the GetDeviceCaps function, later in this chapter. 


BitBit 


Table 4.1 lists the various raster-operation codes for the dwRop parameter: 


Table 4.1 


Code 


BLACKNESS 
DSTINVERT 
MERGECOPY 


MERGEPAINT 


NOTSRCCOPY 
NOTSRCERASE 


PATCOPY 
PATINVERT 


PATPAINT 


SRCAND 


SRCCOPY 
SRCERASE 


SRCINVERT 
SRCPAINT 


WHITENESS 


Raster Operations 


Description 


Tums all output black. 
Inverts the destination bitmap. 


Combines the pattern and the source bitmap using the Boolean AND 
operator. 


Combines the inverted source bitmap with the destination bitmap using 
the Boolean OR operator. 


Copies the inverted source bitmap to the destination. 


Inverts the result of combining the destination and source bitmaps using 
the Boolean OR operator. 


Copies the pattern to the destination bitmap. 


Combines the destination bitmap with the pattern using the Boolean 
XOR operator. 


Combines the inverted source bitmap with the pattern using the 
Boolean OR operator. Combines the result of this operation with the 
destination bitmap using the Boolean OR operator. 


Combines pixels of the destination and source bitmaps using the 
Boolean AND operator. 


Copies the source bitmap to the destination bitmap. 


Inverts the destination bitmap and combines the result with the source 
bitmap using the Boolean AND operator. 


Combines pixels of the destination and source bitmaps using the 
Boolean XOR operator. 


Combines pixels of the destination and source bitmaps using the 
Boolean OR operator. 


Turns all output white. 


For a complete list of the raster-operation codes, see Chapter 11, “Binary and Ternary 
Raster-Operation Codes,” in Reference, Volume 2. 
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BringWindowToTop 


Syntax 


void BringWindowToTop(iWnd) 


This function brings a pop-up or child window to the top of a stack of overlapping 
windows. In addition, it activates pop-up and top-level windows. The BringWindowTo- 
Top function should be used to uncover any window that is partially or completely ob- 
scured by any overlapping windows. 


Parameter Type/Description 
hWnd HWND Identifies the pop-up or child window that is to be brought 
to the top. 
Return Value None. 
BuildCommDCB 


Syntax 


Return Value 


Comments 


int BuildCommDCB(pDef, [pDCB) 


This function translates the definition string specified by the /pDef parameter into appro- 
priate device-control block codes and places these codes into the block pointed to by the 
IpDCB parameter. 


Parameter Type/Description 


lpDef LPSTR Points to a null-terminated character string that specifies 
the device-control information for a device. The string must have the 
same form as the DOS MODE command-line parameter. 


IpDCB DCB FAR * Points to the DCB data structure that is to receive the 
translated string. The structure defines the control setting for the se- 
rial-communication device. 


The return value specifies the result of the function. It is zero if the string is translated. It is 
negative if an error occurs. 


The BuildCommDCB function only fills the buffer. An application should call SetComm- 
State to apply these settings to the port. Also, by default, BuildCommDCB specifies 
Xon/Xoff and hardware flow control as disabled. An application should set the appropriate 
fields in the DCB data structure to enable flow control. 
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CallMsgFilter 


CallMsgFilter 
Syntax 


Return Value 


Comments 


BOOL § CallMsgFilter(/pMsg, nCode) 


This function passes the given message and code to the current message filter function. 
The message filter function is an application-specified function that examines and modi- 
fies all messages. An application specifies the function by using the SetWindowsHook 
function. 


Parameter Type/Description 


IpMsg LPMSG Points to an MSG data structure that contains the 
message to be filtered. 


nCode int Specifies a code used by the filter function to determine how to 
process the message. 


The return value specifies the state of message processing. It is FALSE if the message 
should be processed. It is TRUE if the message should not be processed further. 


The CallIMsgFilter function is usually called by Windows to let applications examine and 
control the flow of messages during internal processing in menus and scroll bars or when 
moving or sizing a window. 


Values given for the nCode parameter must not conflict with any of the MSGF_ and HC_ 
values passed by Windows to the message filter function. 


CallWindowProc 


Syntax 


LONG  CallWindowProc(/pPrevWndFunc, hWnd, wMsg, wParam, lParam) 


This function passes message information to the function specified by the JpPrevWndF unc 
parameter. The CallWindowProc function is used for window subclassing. Normally, all 
windows with the same class share the same window function. A subclass is a window or 
set of windows belonging to the same window class whose messages are intercepted and 
processed by another function (or functions) before being passed to the window function 
of that class. 


The SetWindowLong function creates the subclass by changing the window function as- 
sociated with a particular window, causing Windows to call the new window function in- 
stead of the previous one. Any messages not processed by the new window function must 
be passed to the previous window function by calling CallWindowProc. This allows a 
chain of window functions to be created. 
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Parameter Type/Description 

IpPrevWndFunc FARPROC Is the procedure-instance address of the previous 
window function. 

hWnd HWND Identifies the window that receives the message. 

wMsg WORD Specifies the message number. 

wParam _ WORD Specifies additional message-dependent information. 

[Param DWORD Specifies additional message-dependent informa- 
tion. 


Return Value 


Catch 
Syntax 


Return Value 


Comments 


The return value specifies the result of the message processing. The possible return values 
depend on the message sent. 


int Catch(/pCatchBuf) 


This function catches the current execution environment and copies it to the buffer pointed 
to by the /pCatchBuf parameter. The execution environment is the state of all system 
registers and the instruction counter. 


Parameter Type/Description 


[pCatchBuf LPCATCHBUF Points to the CATCHBUF structure that 
will receive the execution environment. 


The return value specifies whether the execution environment is copied to the buffer. It is 
zero if the environment is copied to the buffer. 


The Throw function uses the buffer to restore the execution environment to its previous 
values. 


The Catch function is similar to the C run-time setjmp function (which is incompatible 
with the Windows environment). 
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ChangeClipboardChain 
Syntax BOOL  ChangeClipboardChain(iWnd, hWndNext) 
This function removes the window specified by the AWnd parameter from the chain of clip- 


board viewers and makes the window specified by the hWndNext parameter the descen- 
dant of the AWnd parameter’s ancestor in the chain. 


Parameter Type/Description 


hWnd HWND Identifies the window that is to be removed from the 
chain. The handle must previously have been passed to the Set- 
Clipboard Viewer function. 


hWndNext HWND Identifies the window that follows hWnd in the clip- 
board-viewer chain (this is the handle returned by the 
SetClipboard Viewer function, unless the sequence was 
changed in response to a WM_CHANGECBCHAIN message). 


Return Value The return value specifies the status of the hWnd window. It is nonzero if the window is 
found and removed. Otherwise, it is zero. 


ChangeMenu 


The Microsoft Windows version 3.0 SDK has replaced this function with five specialized 
functions. These new functions are: 


Function Description 

AppendMenu Appends a menu item to the end of a menu. 

DeleteMenu Deletes a menu item from a menu, destroying the menu item. 

InsertMenu Inserts a menu item into a menu. 

ModifyMenu Modifies a menu item in a menu. 

RemoveMenu Removes a menu item from a menu but does not destroy the 
menu item. 


Applications written for SDK versions 2.1 and earlier may continue to call ChangeMenu 
as previously documented. New applications should call the new functions listed above. 
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ChangeSelector 


_ Syntax 


Return Value 


WORD ChangeSelector(wDestSelector, wSourceSelector) 


This function generates a code selector that corresponds to a given data selector, or a data 
selector that corresponds to a given code selector. 


The wSourceSelector parameter specifies the selector to be copied and converted; the 
wDestSelector parameter is a selector previously allocated by a call to the AllocSelector 
function. ChangeSelector modifies the destination selector to have the same properties as 
the source selector, but with the opposite code or data attribute. This function changes only 
the attributes of the selector, not the value of the selector. 


Parameter Type/Description 


wDestSelector WORD _ Specifies a selector previously allocated by Alloc- 
Selector that receives the converted selector. 


wSourceSelector WORD _Specifies the selector to be converted. 


The return value is the copied and converted selector. It is zero if the function failed. 


Comments Windows does not attempt to track changes to the source selector. Consequently, the appli- 
cation should use the converted destination selector immediately after it is returned by this 
function before any movement of memory can occur. 

An application should not use this function unless it is absolutely necessary. Use of this 
function violates preferred Windows programming practices. 

CheckDigButton 

Syntax void CheckDlgButton(hD/g, nIDButton, wCheck) 


This function places a checkmark next to or removes a checkmark from a button control, 
or changes the state of a three-state button. The CheckDlgButton function sends a 


_BM_SETCHECK message to the button control that has the specified ID in the given 


dialog box. 
Parameter Type/Description 
hDlg HWND Identifies the dialog box that contains the button. 


nIDButton int Specifies the button control to be modified. 
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Parameter Type/Description 


wCheck WORD _ Specifies the action to take. If the wCheck parameter 
is nonzero, the CheckDlgButton function places a checkmark 
next to the button; if zero, the checkmark is removed. For three- 
state buttons, if wCheck is 2, the button is grayed; if wCheck is 
1, it is checked; if wCheck is 0, the checkmark is removed. 


Return Value None. 
CheckMenultem 
Syntax BOOL CheckMenultem(iMenu, wlIDCheckltem, wCheck) 


This function places checkmarks next to or removes checkmarks from menu items in the 
pop-up menu specified by the hMenu parameter. The w/DCheckItem parameter specifies 
the item to be modified. 


Parameter Type/Description 

hMenu HMENU _ Identifies the menu. 

wlDCheck- WORD _ Specifies the menu item to be checked. 

Item 

wCheck WORD _ Specifies how to check the menu item and how to deter- 


mine the item’s position in the menu. The wCheck parameter can be a 
combination of the MF_CHECKED or MF_UNCHECKED with 
MF_BYPOSITION or MF_BYCOMMAND flags. These flags can 
be combined by using the bitwise OR operator. They have the follow- 
ing meanings: 


Value Meaning 


MF_BYCOMMAND Specifies that the w/[DCheckltem para- 
meter gives the menu-item ID 
(MF_BYCOMMAND is the default). 


MF_BYPOSITION Specifies that the wJ[DCheckItem para- 
meter gives the position of the menu item 
(the first item is at position zero). 


MF_CHECKED Adds checkmark. 
MF_UNCHECKED Removes checkmark. 
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Return Value 


Comments 


The return value specifies the previous state of the item. It is either MF_CHECKED or 
MF_UNCHECKED. The return value is —1 if the menu item does not exist. 


The w/DCheckItem parameter may identify a pop-up menu item as well as a menu item. 
No special steps are required to check a pop-up menu item. 


Top-level menu items cannot be checked. 


A pop-up menu item should be checked by position since it does not have a menu-item 
identifier associated with it. 


CheckRadioButton 


Syntax 


void CheckRadioButton(hDlg, nIDFirstButton, nIDLastButton, nIDCheckButton) 


This function checks the radio button specified by the n/DCheckButton parameter and re- 
moves the checkmark from all other radio buttons in the group of buttons specified by the 
nlDFirstButton and nIDLastButton parameters. The CheckRadioButton function sends a 
BM_SETCHECK message to the radio-button control that has the saa ID in the 
given dialog box. 


Parameter Type/Description 
hDlg HWND Identifies the dialog box. 
nlDFirstButton int Specifies the integer identifier of the first radio button in 
the group. 
nlIDLastButton int Specifies the integer identifier of the last radio button in 
. the group. 
nIDCheckButton int Specifies the integer identifier of the radio button to be 
checked. 
Return Value None. 
ChildWindowFromPoint 


Syntax 


HWND ChildWindowFromPoint(hWndParent, Point) 


This function determines which, if any, of the child windows belonging to the given parent 
window contains the specified point. 
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Chord 


Return Value 


Chord 
Syntax 


Parameter Type/Description 

hWndParent HWND _Identifies the parent window. 

Point POINT Specifies the client coordinates of the point to be 
tested. 


The return value identifies the child window that contains the point. It is NULL if the 
given point lies outside the parent window. If the point is within the parent window but is 
not contained within any child window, the handle of the parent window is returned. 


BOOL Chord(hDC, X1, Y1, X2, Y2, X3, Y3, X4, Y4) 


This function draws a chord (a region bounded by the intersection of an ellipse and a line 
segment). The (X/, YJ) and (X2, Y2) parameters specify the upper-left and lower-right 
corners, respectively, of a rectangle bounding the ellipse that is part of the chord. The (X3, 
Y3) and (X4, Y4) parameters specify the endpoints of a line that intersects the ellipse. The 
chord is drawn by using the selected pen and filled by using the selected brush. 


Parameter Type/Description 

hDC © HDC Identifies the device context in which the chord will appear. 

X1 int Specifies the x-coordinate of the bounding rectangle’s upper- 
left corner. 

Y1 int Specifies the y-coordinate of the bounding rectangle’s upper- 
left corner. 

X2 int Specifies the x-coordinate of the bounding rectangle’s lower- 
right corner. 

Y2 int Specifies the y-coordinate of the bounding rectangle’s lower- 
right corner. 

X3 ' int Specifies the x-coordinate of one end of the line segment. 

Y3 int Specifies the y-coordinate of one end of the line segment. 

X4 int Specifies the x-coordinate of one end of the line segment. 


Y4 int Specifies the y-coordinate of one end of the line segment. 
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Return Value The return value specifies whether or not the arc is drawn. It is nonzero if the arc is drawn. 
Otherwise, it is zero. 


ClearCommBreak 
2 i Syntax int ClearCommBreak(nCid) 


This function restores character transmission and places the transmission line in a non- 
break state. 


Parameter Type/Description 


nCid int Specifies the communication device to be restored. The Open- 
Comm function returns this value. 


Return Value The return value specifies the result of the function. It is zero if the function is successful. 
It is negative if the nCid parameter is not a valid device. 


ClientToScreen 
Syntax void ClientToScreen(hWnd, IpPoint) 


This function converts the client coordinates of a given point on the display toscreen  _ 

coordinates. The ClientToScreen function uses the client coordinates in the POINT data 

structure, pointed to by the /pPoint parameter, to compute new screen coordinates; it then 

replaces the coordinates in the structure with the new coordinates. The new screen coordi- 
nates are relative to the upper-left corner of the system display. 


Parameter Type/Description 

hWnd HWND Identifies the window whose client area will be used for. 
the conversion. 

IpPoint LPPOINT Points to a POINT data structure that contains the 


client coordinates to be converted. 


Return Value None. 


Comments The ClientToScreen function assumes that the given point is in client coordinates and is 
relative to the given window. 
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ClipCursor 


ClipCursor 
Syntax 


Return Value 


Comments 


CloseClipboard 


Syntax 


Return Value — 


CloseComm 
Syntax 


void ClipCursor(/pRect) 


This function confines the cursor to the rectangle on the display screen given by the /pRect 
parameter. If a subsequent cursor position, given with the SetCursorPos function or the 
mouse, lies outside the rectangle, Windows automatically adjusts the position to keep the 
cursor inside. If JpRect is NULL, the cursor is free to move anywhere on the display screen. 


Parameter Type/Description 

lpRect LPRECT Points to a RECT data structure that contains the screen 
coordinates of the upper-left and lower-right corners of the confining 
rectangle. 

None. 


The cursor is a shared resource. An application that has confined the cursor to a given 
rectangle must free it before relinquishing control to another application. 


BOOL  CloseClipboard( ) 


This function closes the clipboard. The CloseClipboard function should be called when a 
window has finished examining or changing the clipboard. It lets other applications access 
the clipboard. 


This function has no parameters. 


The return value specifies whether the clipboard is closed. It is nonzero if the clipboard is 
closed. Otherwise, it is zero. 


int CloseComm(nCid) 


This function closes the communication device specified by the nCid parameter and frees 
any memory allocated for the device’s transmit and receive queues. All characters in the 
Output queue are sent before the communication device is closed. 


>) 
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Return Value 


CloseMetaFile 
Syntax 


Return Value 


CloseSound 
Syntax 


Return Value 


CloseWindow 
Syntax 


Parameter Type/Description 


nCid int Specifies the device to be closed. The OpenComm function re- 
tums this value. 


The return value specifies the result of the function. It is zero if the device is closed. It is 
negative if an error occurred. 


HANDLE  CloseMetaFile(hDC) 


This function closes the metafile device context and creates a metafile handle that can be 
used to play the metafile by using the PlayMetaFile function. 


Parameter Type/Description 


hDC HANDLE Identifies the metafile device context to be closed. 


The return value identifies the metafile if the function is successful. Otherwise, it is NULL. 


void CloseSound( ) 


This function closes access to the play device and frees the device for opening by other 
applications. The CloseSound function flushes all voice queues and frees any buffers allo- 
cated for these queues. 


This function has no parameters. 


None. 


void CloseWindow(hWnd) 


This function minimizes the specified window. If the window is an overlapped window, it 
is minimized by removing the client area and caption of the open window from the display 
screen and moving the window’s icon into the icon area of the screen. 
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CombineRgn 


Return Value 


Comments 


CombineRgn 
Syntax 


Parameter 


hWnd 


None. 


Type/Description 


HWND Identifies the window to be minimized. 


This function has no effect if the hWnd parameter is a handle to a pop-up or child window. 


int CombineRgn(hDestRen, hSrcRgnl, hSrcRgn2, nCombineMode) 


This function creates a new region by combining two existing regions. The method used to 
combine the regions is specified by the nCombineMode parameter. 


Parameter 


hDestRgn 


hSrcRgnl 
hSrcRgn2 
nCombineMode 


Type/Description 


HRGN Identifies an existing region that will be replaced by 
the new region. 


HRGN Identifies an existing region. 
HRGN Identifies an existing region. 


int Specifies the operation to be performed on the two ex- 
isting regions. It can be any one of the following values: 


Value Meaning 

RGN_AND Uses overlapping areas of both regions 
(intersection). 

RGN_COPY Creates a copy of region | (identified by 
hSrcRegnl). 

RGN_DIFF Saves the areas of region | (identified by 


the ASrcRgn1 parameter) that are not part 
of region 2 (identified by the hSrcRgn2 


parameter). 
RGN_OR Combines all of both regions (union). 
RGN_XOR Combines both regions but removes over- 


lapping areas. 
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Return Value 


Comments 


CopyMetaFile 
Syntax 


Return Value 


CopyRect 
Syntax 


The return value specifies the type of the resulting region. It can be any one of the follow- 
ing values: ; 


Value | Meaning 

COMPLEXREGION New region has overlapping borders. — 
ERROR No new region created. 

NULLREGION New region is empty. 
SIMPLEREGION New region has no overlapping borders. 


If the hDestRgn parameter does not identify an existing region, the application must pass a 
far pointer to a previously allocated HRGN as the hDestRgn parameter. 


HANDLE CopyMetaFile(hSrcMetaFile, lpFilename) 


This function copies the source metafile to the file pointed to by the /pFilename parameter 
and returns a handle to the new metafile. If IpFilename is NULL, the source is copied to a 
memory metafile. 


Parameter Type/Description 
hSrcMetaFile HANDLE Identifies the source metafile. 
IpFilename - LPSTR Points to a null-terminated character string that speci- 


fies the file that is to receive the metafile. 


The return value identifies the new metafile. 


int CopyRect(/pDestRect, lpSourceRect) 


This function copies the rectangle pointed to by the IpSourceRect parameter to the RECT 
data structure pointed to by the /pDestRect parameter. 
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CountClipboardFormats 


Return Value 


Parameter Type/Description 
IpDestRect LPRECT Points toa RECT data structure. 
IpSourceRect LPRECT Points to a RECT data structure. 


Although the CopyRect function return type is an integer, the return value is not used and 
has no meaning. 


CountClipboardFormats 


Syntax 


" Return Value 


int CountClipboardFormats( ) 
This function retrieves a count of the number of formats the clipboard can render. 


This function has no parameters. 


The return value specifies the number of data formats in the clipboard. 


CountVoiceNotes 


Syntax 


Return Value 


CreateBitmap 
Syntax 


int CountVoiceNotes(nVoice) 


This function retrieves a count of the number of notes in the specified queue. Only those 
queue entries that result from calls to the Set VoiceNote function are counted. 


Parameter Type/Description 


nVoice int Specifies the voice queue to be counted. The first voice queue 
is numbered 1. 


The return value specifies the number of notes in the given queue. 


HBITMAP  CreateBitmap(nWidth, nHeight, nPlanes, nBitCount, IpBits) 


This function creates a device-dependent memory bitmap that has the specified width, 
height, and bit pattern. The bitmap can subsequently be selected as the current bitmap for a 
memory display by using the SelectObject function. 
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Return Value 


Although a bitmap cannot be copied directly to a display device, the BitBlt function can 
copy it from a memory display context (in which it is the current bitmap) to any com- 
patible device. 


Parameter Type/Description 
nWidth int Specifies the width (in pixels) of the bitmap. 
nHeight int Specifies the height (in pixels) of the bitmap. 
nPlanes BYTE — Specifies the number of color planes in the bitmap. Each 
. plane has nWidth x nHeight x nBitCount bits. 
nBitCount BYTE Specifies the number of color bits per display pixel. 
[pBits LPSTR Points to a short-integer array that contains the initial bit- 


map bit values. If it is NULL, the new bitmap is left uninitialized. 
For more information, see the description of the bmBits field in the 
BITMAP data structure in Chapter 7, “Data Types and Structures,” 
in Reference, Volume 2. 


The return value identifies a bitmap if the function is successful. Otherwise, it is NULL. 


CreateBitmapindirect 


Syntax 


Return Value 


HBITMAP CreateBitmapIndirect(/pBitmap) 


This function creates a bitmap that has the width, height, and bit pattern given in the data 
structure pointed to by the /pBitmap parameter. Although a bitmap cannot be directly 
selected for a display device, it can be selected as the current bitmap for a memory display 
and copied to any compatible display device by using the BitBlt function. 


Parameter Type/Description 


[pBitmap BITMAP FAR * Points to a BITMAP data structure that contains 
information about the bitmap. 


The return value identifies a bitmap if the function is successful. Otherwise, it is NULL. 


CreateBrushindirect 
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CreateBrushindirect 
Syntax HBRUSH_CreateBrushIndirect(/pLogBrush) 


Return Value 


Comments 


CreateCaret 
Syntax 


This function creates a logical brush that has the style, color, and pattern given in the data 
structure pointed to by the /pLogBrush parameter. The brush can subsequently be selected 
as the current brush for any device. 


Parameter Type/Description 


IpLogBrush LOGBRUSH FAR * Points to a LOGBRUSH data structure that 
contains information about the brush. 


The return value identifies a logical brush if the function is successful. Otherwise, it is 
NULL. 


A brush created using a monochrome (one plane, one bit per pixel) bitmap is drawn using 
the current text and background colors. Pixels represented by a bit set to 0 will be drawn 
with the current text color, and pixels represented by a bit set to 1 will be drawn with the 
current background color. 


void CreateCaret(hWnd, hBitmap, nWidth, nHeight) 


This function creates a new shape for the system caret and assigns ownership of the caret 
to the given window. The caret shape can be a line, block, or bitmap as defined by the ABit- 
map parameter. If hBitmap is a bitmap handle, the nWidth and nHeight parameters are ig- 
nored; the bitmap defines its own width and height. (The bitmap handle must have been 
previously created by using the CreateBitmap, CreateDIBitmap, or LoadBitmap func- 
tion.) If hBitmap is NULL or 1, nWidth and nHeight give the caret’s width and height (in 
logical units); the exact width and height (in purels) depend on the window’s mapping 
mode. 


If nWidth or nHeight is zero, the caret width or height is set to the system’s window-border 
width or height. Using the window-border width or height guarantees that the caret will be . 
visible on a high-resolution display. 


The CreateCaret function automatically destroys the previous caret shape, if any, regard- 
less of which window owns the caret. Once created, the caret is initially hidden. To show 
the caret, the ShowCaret function must be called. 
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Return Value 


Comments 


Parameter Type/Description 

hWnd -HWND Identifies the window that owns the new caret. 

hBitmap HBITMAP Identifies the bitmap that defines the caret shape. If 
hBitmap is NULL, the caret is solid; if hBitmap is 1, the caret is gray. 

nWidth int Specifies the width of the caret (in logical units). 

nHeight int Specifies the height of the caret (in logical units). 

None. 


The system caret is a shared resource. A window should create a caret only when it has the 
input focus or is active. It should destroy the caret before losing the input focus or becom- 
ing inactive. 


The system’s window-border width or height can be retrieved by using the GetSystem- 
Metrics function with the SM_CXBORDER and SM_CYBORDER indexes. 


CreateCompatibleBitmap 


Syntax 


HBITMAP  CreateCompatibleBitmap(iDC, nWidth, nHeight) 


This function creates a bitmap that is compatible with the device specified by the hDC 
parameter. The bitmap has the same number of color planes or the same bits-per-pixel for- 
mat as the specified device. It can be selected as the current bitmap for any memory device 
that is compatible with the one specified by hDC. 


If hDC is a memory device context, the bitmap returned has the same format as the cur- 
rently selected bitmap in that device context. A memory device context is a block of 
memory that represents a display surface. It can be used to prepare images in memory 
before copying them to the actual display surface of the compatible device. 


When a memory device context is created, GDI automatically selects a monochrome stock 
bitmap for it. 


Since a color memory device context can have either color or monochrome bitmaps 
selected, the format of the bitmap returned by the CreateCompatibleBitmap function is 
not always the same; however, the format of a compatible bitmap for a nonmemory device 
context is always in the format of the device. 
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CreateCompatibleDC 


Return Value 


Parameter 


hDC 
nWidth 
nHeight 


Type/Description 
HDC Identifies the device context. 
int Specifies the width (in bits) of the bitmap. 


int Specifies the height (in bits) of the bitmap. 


The return value identifies a bitmap if the function is successful. Otherwise, it is NULL. 


CreateCompatibleDC 
HDC CreateCompatibleDC(iDC) 


Syntax 


Return Value 


Comments 


This function creates a memory device context that is compatible with the device specified 
by the ADC parameter. A memory device context is a block of memory that represents a 
display surface. It can be used to prepare images in memory before copying them to the ac- 
tual device surface of the compatible device. 


When a memory device context is created, GDI automatically selects a 1-by-1 mono- 
chrome stock bitmap for it. 


Parameter 


hDC 


Type/Description 


HDC Identifies the device context. If DC is NULL, the function 
creates a memory device context that is compatible with the system 
display. 


The return value identifies the new memory device context if the function is successful. 
Otherwise, it is NULL. 


This function can only be used to create compatible device contexts for devices that sup- 
port raster operations. For more information, see the RC_BITBLT raster capability in the 
GetDeviceCaps function, later in this chapter. 


GDI output functions can be used with a memory device context only if a bitmap has been 
created and selected into that context. 


When the application no longer requires the device context, it should free it by calling the 
DeleteDC function. . 


CreateCursor 


4-38 


CreateCursor 


HCURSOR. CreateCursor(h/nstance, nXhotspot, nYhotspot, nWidth, nHeight, 
IpANDbitP lane, IpXORbitP lane) 


Syntax 


Return Value 


CreateDC 
Syntax 


This function creates a cursor that has specified width, height, and bit patterns. 


Parameter 


hInstance 


nX hotspot 
nYhotspot 
nWidth 
nHeight 
lpANDbitPlane 


IpXORbitPlane 


Type/Description 


HANDLE Identifies an instance of the module creating the 
cursor. 


int Specifies the horizontal position of the cursor hotspot. 
int Specifies the vertical position of the cursor hotspot. 
int Specifies the width in pixels of the cursor. 

int Specifies the height in pixels of the cursor. 


LPSTR Points to an array of bytes containing the bit values . 
for the AND mask of the cursor. This can be the bits of a 
device-dependent monochrome bitmap. . 


LPSTR Points to an array of bytes containing the bit values 
for the XOR mask of the cursor. This can be the bits of a 
device-dependent monochrome bitmap. 


The return value identifies the cursor if the function was successful. Otherwise, it is NULL. 


HDC CreateDC(/pDriverName, lpDeviceName, IpOutput, IpInitData) 


This function creates a device context for the specified device. The JpDriverName, IpDevi- 
ceName, and IpOutput parameters specify the device driver, device name, and physical out- 
put medium (file or port), respectively. 


Parameter 


IpDriverName 


Type/Description 


LPSTR Points to a null-terminated character string that speci- 
fies the DOS filename (without extension) of the device driver 
(for example, Epson ®). 
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CreateDialog 


Return Value 


Comments 


CreateDialog 
Syntax 


Parameter Type/Description 


IpDeviceName LPSTR Points to a null-terminated character string that speci- 
fies the name of the specific device to be supported (for 
example, Epson FX-80). The /pDeviceName parameter is used if 
the module supports more than one device. 


lpOutput LPSTR Points to a null-terminated character string that speci- 
fies the DOS file or device name for the physical output medium 
(file or output port). 


IpInitData LPDEVMODE Points toa DEVMODE data structure con- 
taining device-specific initialization data for the device driver. 
The ExtDeviceMode retrieves this structure filled in for a given 
device. The /p/nitData parameter must be NULL if the device 
driver is to use the default initialization (if any) specified by the 
user through the Control Panel. 


The return value identifies a device context for the specified device if the function is 
successful. Otherwise, it is NULL. 


DOS device names follow DOS conventions; an ending colon (:) is recommended, but op- 
tional. Windows strips the terminating colon so that a device name ending with a colon is 
mapped to the same port as the same name without a colon. The driver and port names 
must not contain leading or trailing spaces. 


HWND  CreateDialog(/nstance, lpTemplateName, hWndParent, lpDialogFunc) 


This function creates a modeless dialog box that has the size, style, and controls defined by 
the dialog-box template given by the [pTemplateName parameter. The hWndParent para- 
meter identifies the application window that owns the dialog box. The dialog function 
pointed to by the IpDialogFunc parameter processes any messages received by the dialog 
box. 


The CreateDialog function sends a WM_INITDIALOG message to the dialog function 
before displaying the dialog box. This message allows the dialog function to initialize the 
dialog-box controls. 


CreateDialog returns immediately after creating the dialog box. It does not wait for the 
dialog box to begin processing input. 
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Return Value 


Comments 


Callback Function 


Parameter Type/Description 


hInstance HANDLE Identifies an instance of the module whose exe- 
cutable file contains the dialog-box template. 


IpTemplateName LPSTR Points to a character string that names the dialog-box 
template. The string must be a null-terminated character string. 

hWndParent HWND Identifies the window that owns the dialog box. 

IpDialogFunc FARPROC Is the procedure-instance address for the dialog 


function. See the following “Comments” section for details. 


The return value is the window handle of the dialog box. It is NULL if the function cannot 
create the dialog box. 


Use the WS_VISIBLE style for the dialog-box template if the dialog box should appear in 
the parent window upon creation. 


Use the Destroy Window function to mestroy a tialog box created by the CreateDialog 
function. 


A dialog box can contain up to 255 controls. 


The callback function must use the Pascal calling convention and must be declared FAR. 


BOOL FAR PASCAL DialogFunc(hDlg, wMsg, wParam, lParam) 
HWND /Dig; 

WORD wMszg; 

WORD wParam; 

DWORD /Param; 


DialogFunc is a placeholder for the application-supplied function name. The actual name 
must be exported by including it in an EXPORTS statement in the application’s module- 
definition file. 


Parameter Definition 

hDig Identifies the dialog box that receives the message. 

wMsg Specifies the message number. 

wParam Specifies 16 bits of additional message-dependent information. 


lParam Specifies 32 bits of additional message-dependent information. 
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CreateDialogindirect 


Return Value 


Except in response to the WM_INITDIALOG message, the dialog function should return 
nonzero if the function processes the message, and zero if it does not. In response to a 
WM_INITDIALOG message, the dialog function should return zero if it calls the SetFo- 
cus function to set the focus to one of the controls in the dialog box. Otherwise, it should 
return nonzero, in which case Windows will set the focus to the first control in the dialog 
box that can be given the focus. 


Comments 


The dialog function is used only if the dialog class is used for the dialog box. This is the de- 
fault class and is used if no explicit class is given in the dialog-box template. Although the 
dialog function is similar to a window function, it must not call the DefWindowProc func- 
tion to process unwanted messages. Unwanted messages are processed internally by the 
dialog-class window function. 


The dialog-function address, passed as the [pDialogFunc parameter, must be created by 
using the MakeProcInstance function. 


CreateDialogIndirect 


Syntax 


HWND CreateDialogIndirect(h/nstance, lpDialogTemplate, hWndParent, 
IpDialogFunc) 


This function creates a modeless dialog box that has the size, style, and controls defined by 
the dialog-box template given by the [pDialogTemplate parameter. The hWndParent para- 
meter identifies the application window that owns the dialog box. The dialog function 
pointed to by the /pDialogFunc parameter processes any messages received by the dialog 
box. 


The CreateDialogIndirect function sends a WM_INITDIALOG message to the dialog 
function before displaying the dialog box. This message allows the dialog function to ini- 
tialize the dialog-box controls. 


CreateDialogIndirect returns immediately after creating the dialog box. It does not wait 
for the dialog box to begin processing input. 


Parameter Type/Description 


hInstance HANDLE Identifies an instance of the module whose exe- 
cutable file contains the dialog-box template. 


IpDialogTemplate LPSTR Points to a block of memory that contains a 
DLGTEMPLATE data structure. 


hWndParent HWND Identifies the window that owns the dialog box. 


CreateDialogIndirect ede 


Parameter Type/Description 


IpDialogFunc FARPROC Is the procedure-instance address of the dialog 
function. See the following ““Comments” section for details. 


Return Value The return value is the window handle of the dialog box. It is NULL if the function cannot 
create either the dialog box or any controls in the dialog box. 


Comments Use the WS_VISIBLE style in the dialog-box template if the dialog box should appear in 
the parent window upon creation. 


A dialog box can contain up to 255 controls. 


The callback function must use the Pascal calling convention and must be declared FAR. 


Callback Function BOOL FAR PASCAL DialogFunc(hDlg, wMsg, wParam, lParam) 
HWND ADI; 
WORD wMszg; 
WORD wParam; 
DWORD /Param; 


DialogFunc is a placeholder for the application-supplied function name. The actual name 
must be exported by including it in an EXPORTS statement in the application’s module- 
definition file. 


Parameter Definition 

hDlg Identifies the dialog box that receives the message. 

wMsg Specifies the message number. 

wParam Specifies 16 bits of additional message-dependent information. 
[Param Specifies 32 bits of additional message-dependent information. 


Return Value 


Except in response to the WM_INITDIALOG message, the dialog function should return 
nonzero if the function processes the message, and zero if it does not. In response to a 
WM_INITDIALOG message, the dialog function should return zero if it calls the SetFo- 
cus function to set the focus to one of the controls in the dialog box. Otherwise, it should 
return nonzero, in which case Windows will set the focus to the first control in the dialog 
box that can be given the focus. 
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Comments 


The dialog function is used only if the dialog class is used for the dialog box. This is the de- 
fault class and is used if no explicit class is given in the dialog-box template. Although the 
dialog function is similar to a window function, it must not call the DefWindowProc func- 
tion to process unwanted messages. Unwanted messages are processed internally by the 
dialog-class window function. 


The dialog-function address, passed as the /pDialogFunc parameter, must be created by 
using the MakeProclInstance function. 


CreateDialogindirectParam 


Syntax 


Return Value 


HWND  CreateDialogIndirectParam(h/nstance, lpDialogTemplate, hWndParent, 
IpDialogFunc, dwlnitParam) 


This function creates a modeless dialog box, sends a WM_INITDIALOG message to the 
dialog function before displaying the dialog box, and passes dw/nitParam as the message 
IParam. This message allows the dialog function to initialize the dialog-box controls. 
Otherwise, this function is identical to the CreateDialogIndirect function. 


For more information on creating a modeless dialog box, see the description of the Create- 
DialogIndirect function. 


Parameter Type/Description 


hInstance HANDLE Identifies an instance of the module whose exe- 
cutable file contains the dialog-box template. 


IpDialogTemplate LPSTR Points to a block of memory that contains a 
DLGTEMPLATE data structure. 


hWndParent HWND Identifies the window that owns the dialog box. 


IpDialogFunc FARPROC Is the procedure-instance address of the dialog 
function. For details, see the “Comments” section in the descrip- 
tion of the CreateDialogIndirect function. 


dwlnitParam DWORD Isa 32-bit value which CreateDialogIndirect- 
Param passes to the dialog function when it creates the dialog 
box. 


The return value is the window handle of the dialog box. It is NULL if the function cannot 
create either the dialog box or any controls in the dialog box. 
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CreateDialogParam 


Syntax 


Return Value 


HWND  CreateDialogParam(h/nstance, lpTemplateName, hWndParent, lpDialogF unc, 
dwInitParam) 


This function creates a modeless dialog box, sends a WM_INITDIALOG message to the 
dialog function before displaying the dialog box, and passes dwInitParam as the message 
lParam. This message allows the dialog function to initialize the dialog-box controls. 
Otherwise, this function is identical to the CreateDialog function. 


For more information on creating a modeless dialog box, see the description of the Create- 
Dialog function. 


Parameter Type/Description 


hInstance HANDLE Identifies an instance of the module whose exe- 
cutable file contains the dialog-box template. 


lpTemplateName LPSTR Points to a character string that names the dialog-box 
template. The string must be a null-terminated character string. 

hWndParent HWND Identifies the window that owns the dialog box. 

IpDialogFunc FARPROC Is the procedure-instance address for the dialog 
function. For details, see the “Comments” section of the Create- 
Dialog function. 

dwlnitParam DWORD Isa 32-bit value which CreateDialogParam passes 


to the dialog function when it creates the dialog box. 


The return value is the window handle of the dialog box. It is —1 if the function cannot 
create the dialog box. 


CreateDIBitmap 


Syntax 


HBITMAP  CreateDIBitmap(hDC, IpInfoHeader, dwUsage, IpInitBits, lpInitInfo, 
wUsage) 


This function creates a device-specific memory bitmap from a device-independent bitmap 
(DIB) specification and optionally sets bits in the bitmap. 
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Return Value 


Comments 


Parameter Type/Description 
hDC HDC Identifies the device context. 
lpInfoHeader LPBITMAPINFOHEADER _ Points toa BITMAPINFO- 


HEADER structure that describes the size and format of the 
device-independent bitmap. 


dwUsage DWORD Indicates whether the memory bitmap is to be ini- 
tialized. If dwUsage is set to CBM_INIT, CreateDIBitmap will 
initialize the bitmap with the bits specified by /p/nitBits and [pIn- 
itInfo. 


IpInitBits LPSTR Points to a byte array that contains the initial bitmap 
values. The format of the bitmap values depends on the biBit- 
Count field of the BITMAPINFO structure identified by 
IpInitInfo. See the description of the BITMAPINFO data struc- 
ture in Chapter 7, “Data Types and Structures,” in Reference, 
Volume 2, for more information. 


IpInitInfo LPBITMAPINFO Points toa BITMAPINFO data structure 
that describes the dimensions and color format of /p/nitBits. 
wUsage WORD _ Specifies whether the bmiColors[ ] fields of the /p/ni- 


tInfo data structure contain explicit RGB values or indexes into 
the currently realized logical palette. The wUsage parameter 
must be one of the following values: 


Value Meaning 


DIB_PAL_COLORS The color table consists of an 
array of 16-bit indexes into 
the currently realized logical 
palette. 


DIB_RGB_ COLORS The color table contains lit- 
eral RGB values. 


The return value identifies a bitmap if the function is successful. Otherwise, itis NULL. © 


This function also accepts a device-independent bitmap specification formatted for 
Microsoft OS/2 Presentation Manager versions 1.1 and 1.2 if the /pInfoHeader points to a 
BITMAPCOREHEADER data structure and the /p/nitInfo parameter points to a 
BITMAPCOREINFO data structure. 
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CreateDIBPatternBrush 
Syntax HBRUSH  CreateDIBPatternBrush(hPackedDIB, wUsage) 


This function creates a logical brush that has the pattern specified by the device-inde- 
pendent bitmap (DIB) defined by the the hPackedDIB parameter. The brush can sub- 
sequently be selected for any device that supports raster operations. For more information, 
see the RC_BITBLT raster capability in the GetDeviceCaps function, later in this chapter. - 


Parameter Type/Description 


hPackedDIB GLOBALHANDLE Identifies a global memory object con- 
taining a packed device-independent bitmap. To obtain this 
handle, an application calls the GlobalAlloc function to allocate 
a block of global memory and then fills the memory with the 
packed DIB. A packed DIB consists of a BITMAPINFO data 
structure immediately followed by the array of bytes which 
define the pixels of the bitmap. 


wUsage WORD _ Specifies whether the bmiColors[ ] fields of the 
BITMAPINFO data structure contain explicit RGB values or in- 
dexes into the currently realized logical palette. The wUsage 
parameter must be one of the following values: 


Value Meaning 


DIB_PAL_COLORS The color table contains lit- 
eral RGB values. into the 
currently realized logical 
palette. 


DIB_RGB_COLORS The color table consists of an 
array of 16-bit indexes. 


Return Value The return value identifies a logical brush if the function is successful. Otherwise, it is 
NULL. 


CreateDiscardableBitmap | 
Syntax HBITMAP  CreateDiscardableBitmap(hDC, nWidth, nHeight) 


This function creates a discardable bitmap that is compatible with the device identified by 
the hDC parameter. The bitmap has the same number of color planes or the same bits-per- 
pixel format as the specified device. An application can select this bitmap as the current bit- 
map for a memory device that is compatible with the one specified by the hDC parameter. 
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Parameter Type/Description 

hDC HDC Identifies a device context. 

nWidth int Specifies the width (in bits) of the bitmap. 

nHeight int Specifies the height (in bits) of the bitmap. 
Return Value The return value identifies a bitmap if the function is successful. Otherwise, it is NULL. — 
Comments Windows can discard a bitmap created by this function only if an application has not 


selected it into a display context. If Windows discards the bitmap when it is not selected 
and the application later attempts to select it, the SelectObject function will return zero. 
When this occurs, the application should remove the handle to the bitmap by using 


DeleteObject. 
CreateEllipticRgn 
Syntax HRGN  CreateEllipticRgn(X/, Y/, X2, Y2) 


This function creates an elliptical region. 


Parameter Type/Description 


Xl int Specifies the x-coordinate of the upper-left corner of the bound- 
ing rectangle of the ellipse. 


Yl int Specifies the y-coordinate of the upper-left corner of the bound- 
ing rectangle of the ellipse. 


X2 int Specifies the x-coordinate of the lower-right corner of the 
bounding rectangle of the ellipse. 


Y2 int Specifies the y-coordinate of the lower-right corner of the 
bounding rectangle of the ellipse. 


Return Value The return value identifies a new region if the function is successful. Otherwise, it is 
NULL. 
Comments The width of the rectangle, specified by the absolute value of X2 — XJ, must not exceed 


32,767 units. This limit also applies to the height of the rectangle. 
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CreateEllipticRgnindirect 
Syntax HRGN CreateElipticRgnIndirect(/pRect) 


This function creates an elliptical region. 


Parameter Type/Description 


IpRect LPRECT Points to a RECT data structure that contains the coordi- 
nates of the upper-left and lower-right corners of the bounding 
rectangle of the ellipse. 


Return Value The return value identifies a new region if the function is successful. Otherwise, it is 
NULL. 
Comments The width of the rectangle must not exceed 32,767 units. This limit ee to the height of 


the rectangle as well. 


CreateFont 


Syntax . HFONT CreateFont(nHeight, nWidth, nEscapement, nOrientation, nWeight, cltalic, 
cUnderline, cStrikeOut, cCharSet, cOutputPrecision, cClipPrecision, cQuality, 
cPitchAndFamily, lpFacename) 


This function creates a logical font that has the specified characteristics. The logical font 
can subsequently be selected as the font for any device. 


Parameter Type/Description 


nHeight int Specifies the desired height (in logical units) of the font. 
The font height can be specified in three ways: If nHeight is 
greater than zero, it is transformed into device units and matched 
against the cell height of the available fonts. If it is zero, a rea- 
sonable default size is used. If it is less than zero, it is 
transformed into device units and the absolute value is matched 
against the character height of the available fonts. For all height 
comparisons, the font mapper looks for the largest font that does 
not exceed the requested size, and, if there is no such font, looks 
for the smallest font available. 
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Parameter Type/Description 


nWidth int Specifies the average width (in logical units) of characters 
in the font. If Width is zero, the aspect ratio of the device will 
be matched against the digitization aspect ratio of the available 
fonts to find the closest match, determined by the absolute value 
of the difference. 


nEscapement int Specifies the angle (in tenths of degrees) of each line of 
text written in the font (relative to the bottom of the page). 


nOrientation int Specifies the angle (in tenths of degrees) of each 
character’s baseline (relative to the bottom of the page). 


nWeight int Specifies the desired weight of the font in the range 0 to 
1000 (for example, 400 is normal, 700 is bold). If nWeight is 
zero, a default weight is used. 


cltalic BYTE Specifies whether the font is italic. 

cUnderline BYTE Specifies whether the font is underlined. 

cStrikeOut BYTE = Specifies whether characters in the font are struck out. 
cCharSet BYTE Specifies the desired character set. The following 


values are predefined: 


ANSI_CHARSET 
OEM_CHARSET 
SYMBOL_CHARSET 


The OEM character set is system-dependent. 


Fonts with other character sets may exist in the system. If an 
application uses a font with an unknown character set, it should 
not attempt to translate or interpret strings that are to be ren- 
dered with that font. Instead, the strings should be passed 
directly to the output device driver. 


cOutputPrecision BYTE Specifies the desired output precision. The output pre- 
cision defines how closely the output must match the requested 
font’s height, width, character orientation, escapement, and 
pitch. It can be any one of the following values: 


OUT_CHARACTER_PRECIS 
OUT_DEFAULT_PRECIS 
OUT_STRING_PRECIS 
OUT_STROKE_PRECIS 


CreateFont 
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Parameter 


cClipPrecision 


cQuality 


cPitchAndFamily 


IpFacename 


Type/Description 


BYTE Specifies the desired clipping precision. The clipping 
precision defines how to clip characters that are partially outside 
the clipping region. It can be any one of the following values: 


CLIP_CHARACTER_PRECIS 
CLIP_DEFAULT_PRECIS 
CLIP_STROKE_PRECIS 


BYTE Specifies the desired output quality. The output quality 
defines how carefully GDI must attempt to match the logical- 
font attributes to those of an actual physical font. It can be any 
one of the following values: 


DEFAULT_QUALITY 
DRAFT_QUALITY 
PROOF_QUALITY 


BYTE Specifies the pitch and family of the font. The two low- 
order bits specify the pitch of the font and can be any one of the 
following values: , 


DEFAULT_PITCH 
FIXED_PITCH 
VARIABLE_PITCH 


The four high-order bits of the field specify the font family and 
can be any one of the following values: 


FF_DECORATIVE 
FF_DONTCARE 
FF_MODERN 
FF_ROMAN 
FF_SCRIPT 
FF_SWISS 


LPSTR Points to a null-terminated character string that speci- 
fies the typeface name of the font. The length of this string must 
not exceed 30 characters. The EnumFonts function can be used 
to enumerate the typeface names of all currently available fonts. 
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CreateFontindirect 


Return Value 


The return value identifies a logical font if the function is successful. Otherwise, it is 
NULL. 


Comments The CreateFont function does not create a new font. It merely selects the closest match 
from the fonts available in GDI’s pool of physical fonts. 
‘c 
CreateFontindirect 
Syntax HFONT CreateFontIndirect(/pLogFont) 


Return Value 


Comments 


This function creates a logical font that has the characteristics given in the data structure 
pointed to by the /pLogFont parameter. The font can subsequently be selected as the cur- 
rent font for any device. 


Parameter Type/Description 


IpLogFont LOGFONT FAR * Points toa LOGFONT data structure that de- 
fines the characteristics of the logical font. 


The return value identifies a logical font if the function is successful. Otherwise, it is 
NULL. 


The CreateFontIndirect function creates a logical font that has all the specified charac- 
teristics. When the font is selected by using the SelectObject function, GDI’s font mapper 
attempts to match the logical font with an existing physical font. If it fails to find an exact 
font, it provides an alternate whose characteristics match as many of the requested charac- 
teristics as possible. For a description of the font mapper, see Chapter 2, “Graphics Device 
Interface Functions.” 


CreateHatchBrush 


Syntax 


HBRUSH CreateHatchBrush(n/ndex, crColor) 


This function creates a logical brush that has the specified hatched pattern and color. The 
brush can subsequently be selected as the current brush for any device. 
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Parameter Type/Description 


nIndex int Specifies the hatch style of the brush. It can be any one of the 
following values: 


Value Meaning 

HS_BDIAGONAL 45-degree downward hatch (left to 
right) 

HS_CROSS Horizontal and vertical crosshatch 

HS_DIAGCROSS 45-degree crosshatch 

HS_FDIAGONAL 45-degree upward hatch (left to 
right) 

HS_HORIZONTAL Horizontal hatch 
HS_VERTICAL Vertical hatch 
crColor COLORREF _ Specifies the foreground color of the brush (the 


color of the hatches). 


Return Value The return value identifies a logical brush if the function is successful. Otherwise, it is 
NULL. 

CreatelC 

Syntax HDC CreateIC(/pDriverName, lpDeviceName, lpOutput, IpInitData) 


This function creates an information context for the specified device. The information con- 
text provides a fast way to get information about the device without creating a device con- 


text. 

Parameter Type/Description 

IpDriverName __ LPSTR Points to a null-terminated character string that speci- 
fies the DOS filename (without extension) of the device driver 
(for example, EPSON). . 

IpDeviceName LPSTR Points to a null-terminated character string that speci- 


fies the name of the specific device to be supported (for 
example, EPSON FX-80). The IpDeviceName parameter is used 
if the module supports more than one device. 
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Parameter Type/Description 

IpOutput LPSTR Points to a null-terminated character string that speci- 
fies the DOS file or device name for the physical output medium 
(file or port). 

IpInitData LPSTR Points to device-specific initialization data for the 
device driver. The /p/nitData parameter must be NULL if the 
device driver is to use the default initialization (if any) specified 
by the user through the Control Panel. 

Return Value The return value identifies an information context for the specified device if the function is 
successful. Otherwise, it is NULL. 
Comments DOS device names follow DOS conventions; an ending colon (:) is recommended, but op- 


tional. Windows strips the terminating colon so that a device name ending with a colon is 
mapped to the same port as the same name without a colon. 


The driver and port names must not contain leading or trailing spaces. 


GDI output functions cannot be used with information contexts. 
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Syntax HICON _CreateIcon(h/nstance, nWidth, nHeight, nPlanes, nBitsPixel, IpANDbits, 


IpXORbits) 


This function creates an icon that has specified width, height, colors, and bit patterns. 


Parameter 


hInstance 


nWidth 
nHeight 


nPlanes 


nBitsPixel 


Type/Description 


HANDLE Identifies an instance of the module creating the 
icon. 


int Specifies the width in pixels of the icon. 
int Specifies the height in pixels of the icon. 


BYTE Specifies the number of planes in the XOR mask of 
the icon. 


BYTE Specifies the number of bits per pixel in the XOR 
mask of the icon. 
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Parameter Type/Description 


IpANDbits LPSTR Points to an array of bytes that contains the bit 
values for the AND mask of the icon. This array must specify 
a monochrome mask. 


IpXORbits LPSTR Points to an array of bytes that contains the bit 
values for the XOR mask of the icon. This can be the bits of a 
monochrome or device-dependent color bitmap. 


Return Value The return value identifies an icon if the function is successful. Otherwise, it is NULL. 
CreateMenu 
Syntax HMENU CreateMenu( ) 


This function creates a menu. The menu is initially empty, but can be filled with menu 
items by using the AppendMenu or InsertMenu function. 


This function has no parameters. 


Return Value The return value identifies the newly created menu. It is NULL if the menu cannot be 
created. 

CreateMetaFile 

Syntax HANDLE CreateMetaFile(/pFilename) 


This function creates a metafile device context. 


Parameter Type/Description 


IpFilename LPSTR Points to a null-terminated character string that specifies 
the name of the metafile. If the JpFilename parameter is NULL, a 
device context for a memory metafile is returned. 


Return Value The return value identifies a metafile device context if the function is successful. Other- 
wise, itis NULL. 
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CreatePalette 


CreatePalette 


Syntax 


Return Value 


HPALETTE CreatePalette(/pLogPalette) 


This function creates a logical color palette. 


Parameter Type/Description 


IpLogPalette LPLOGPALETTE Points toa LOGPALETTE data structure 
that contains information about the colors in the logical palette. 


The return value identifies a logical palette if the function was successful. Otherwise, it is 
NULL. 


CreatePatternBrush 


Syntax 


Return Value 


Comments 


HBRUSH CreatePatternBrush(hBitmap) 


This function creates a logical brush that has the pattern specified by the Bitmap para- 
meter. The brush can subsequently be selected for any device that supports raster opera- 
tions. For more information, see the RC_BITBLT raster capability in the GetDeviceCaps 
function, later in this chapter. 


Parameter Type/Description 


hBitmap HBITMAP Identifies the bitmap. It is assumed to have been 
created by using the CreateBitmap, CreateBitmapIndirect, Load- 
Bitmap, or CreateCompatibleBitmap function. The minimum size 
for a bitmap to be used in a fill pattern is 8-by-8. 


The return value identifies a logical brush if the function is successful. Otherwise, it is 
NULL. 


A pattern brush can be deleted without affecting the associated bitmap by using the 
DeleteObject function. This means the bitmap can be used to create any number of pattern 
brushes. 


A brush created using a monochrome (one plane, one bit per pixel) bitmap is drawn using 
the current text and background colors. Pixels represented by a bit set to 0 will be drawn 
with the current text color, and pixels represented by a bit set to 1 will be drawn with the 
current background color. 
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CreatePen 
Syntax HPEN CreatePen(nPenStyle, nWidth, crColor) 


ory This function creates a logical pen having the specified style, width, and color. The pen 
| can be subsequently selected as the current pen for any device. 


Parameter Type/Description 

nPenStyle int Specifies the pen style. It can be any one of the following 
values: 
Pen Style Value 
PS_SOLID 0 
PS_DASH 1 
PS_DOT 2 
PS_DASHDOT 3 
PS_DASHDOTDOT 4 
PS_NULL =) 
PS_INSIDEFRAME 6 


If the width of the pen is greater than 1 and the pen style is PS_IN- 
SIDEFRAME, the line is drawn inside the frame of all primitives 
except polygons and polylines; the pen is drawn with a logical 
(dithered) color if the pen color does not match an available RGB 
value. The PS_INSIDEFRAME style is identical to PS_SOLID if 
the pen width is less than or equal to 1. 


nWidth int Specifies the width of the pen (in logical units). 
crColor COLORREF Specifies the color of the pen. 

Return Value The return value identifies a logical pen if the function is successful. Otherwise, it is 
NULL. 

Comments Pens with a physical width greater than one pixel will always have either null or solid style 


or will be dithered if the pen style is PS_INSIDEFRAME. 
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CreatePenindirect 
Syntax HPEN CreatePenIndirect(/pLogPen) 


This function creates a logical pen that has the style, width, and color given in the data 
structure pointed to by the pLogPen parameter. 


Parameter Type/Description 


IpLogPen LOGPEN FAR * Points to the LOGPEN data structure that con- 
tains information about the logical pen. 


Return Value The return value identifies a logical pen object if the function is successful. Otherwise, it is 
NULL. 
Comments Pens with a physical width greater than one pixel will always have either null or solid style 


or will be dithered if the pen style is PS_INSIDEFRAME. 


CreatePolygonRgn 
Syntax HRGN CreatePolygonRgn(/pPoints, nCount, nPolyFillMode) 


This function creates a polygonal region. 


Parameter Type/Description 

lpPoints LPPOINT Points to an array of POINT data structures. Each 
point specifies the x- and y-coordinates of one vertex of the poly- , 
gon. 

nCount int Specifies the number of points in the array. 

nPolyFillMode int Specifies the polygon-filling mode to be used for filling 


the region. It can be ALTERNATE or WINDING (for an ex- 
planation of these modes, see the SetPolyFillMode function, 
later in this chapter). 


Return Value — The return value identifies a new region if the function is successful. Otherwise, it is 
NULL. 
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CreatePolyPolygonRgn 


Syntax - 


Return Value 


Comments 


HRGN_ CreatePolyPolygonRgn(/pPoints, lpPolyCounts, nCount, nPolyFillMode) 


This function creates a region consisting of a series of closed polygons. The region is filled 
using the mode specified by the nPolyFillMode parameter. The polygons may overlap, but 
they do not have to overlap. 


Parameter Type/Description 


IpPoints LPPOINT Points to an array of POINT data structures that 
define the vertices of the polygons. Each polygon must be a 
closed polygon. The polygons are not automatically closed. The 
polygons are specified consecutively. 


lpPolyCounts LPINT Points to an array of integers, each of which specifies 
the number of points in one of the polygons in the /pPoints array. 


nCount int Specifies the total number of integers in the /pPolyCounts 
array. 


nPolyFillMode int Specifies the filling mode for the region. The nPolyFill- 
Mode parameter may be either of the following values: 


Value Meaning 
ALTERNATE Selects alternate mode. 
WINDING Selects winding number mode. 


The return value identifies the region if the function was successfull. Otherwise, it is 
NULL. ' 


In general, the polygon fill modes differ only in cases where a complex, overlapping poly- 
gon must be filled (for example, a five-sided polygon that forms a five-pointed star with a 
pentagon in the center). In such cases, ALTERNATE mode fills every other enclosed re- 
gion within the polygon (that is, the points of the star), but WINDING mode fills all re- 


gions (that is, the points and the pentagon). 


When the filling mode is ALTERNATE, GDI fills the area between odd-numbered and 
even-numbered polygon sides on each scan line. That is, GDI fills the area between the 
first and second side, between the third and fourth side, and so on. 


To fill all parts of the region, WINDING mode causes GDI to compute and draw a border 
that encloses the region but does not overlap. For example, in WINDING mode, the five- 
sided polygon that forms the star is computed as a ten-sided polygon with no overlapping 
sides; the resulting star is filled. 
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CreatePopupMenu 
Syntax HMENU_ CreatePopupMenu( ) 
This function creates and returns a handle to an empty pop-up menu. 


An application adds items to the pop-up menu by calling InsertMenu and AppendMenu. 
The application can add the pop-up menu to an existing menu or pop-up menu, or it may 
display and track selections on the pop-up menu by calling TrackPopupMenu. 


This function has no parameters. 


Return Value The return value identifies the newly created menu. It is NULL if the menu cannot be 
created. 

CreateRectRgn 

Syntax HRGN CreateRectRgen(X/, Y/, X2, Y2) 


This function creates a rectangular region. 


Parameter Type/Description 
X1 int. Specifies the x-coordinate of the upper-left corner of the re- 
gion. 
Yl int Specifies the y-coordinate of the upper-left corner of the re- 
gion. 
X2 int Specifies the x-coordinate of the lower-right corner of the 
region. 
Y2 int Specifies the y-coordinate of the lower-right corner of the 
region. 
Return Value The return value identifies a new region if the function is successful. Otherwise, it is 
NULL. 
Comments The width of the rectangle, specified by the absolute value of X2 — X/, must not exceed 


32,767 units. This limit applies to the height of the rectangle as well. 
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CreateRectRgnindirect 
Syntax HRGN CreateRectRgnIndirect(/pRect) 


This function creates a rectangular region. 


Parameter Type/Description 
IpRect LPRECT Points to a RECT data structure that contains the 
coordinates of the upper-left and lower-right corners of the re- 
gion. 
Return Value The return value identifies a new region if the function is successful. Otherwise, it is 
NULL. 
Comments The width of the rectangle must not exceed 32,767 units. This limit applies to the height of 


the rectangle as well. 


CreateRoundRectRgn 
Syntax HRGN_ CreateRoundRectRgn(X/, Y/, X2, Y2, X3, Y3) 


This function creates a rectangular region with rounded corners. 


Parameter Type/Description 

AP int Specifies the x-coordinate of the upper-left corner of the region. 

Yl int Specifies the y-coordinate of the upper-left corner of the region. 

X2 int Specifies the x-coordinate of the lower-right corner of the re- 
gion. 

Y2 int Specifies the y-coordinate of the lower-right corner of the re- 
gion. 

X3 int Specifies the width of the ellipse used to create the rounded 
comers. 

Y3 int Specifies the height of the ellipse used to create the rounded 
comers. 

Return Value The return value identifies a new region if the function was successful. Otherwise, it is 


NULL. 
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Comments The width of the rectangle, specified by the absolute value of X2 — X/, must not exceed 
32,767 units. This limit applies to the height of the rectangle as well. 

CreateSolidBrush 

Syntax HBRUSH_ CreateSolidBrush(crColor) 


Return Value 


CreateWindow 
Syntax 


This function creates a logical brush that has the specified solid color. The brush can sub- 
sequently be selected as the current brush for any device. 


Parameter Type/Description 


crColor COLORREF _ Specifies the color of the brush. 


The return value identifies a logical brush if the function is successful. Otherwise, it is 
NULL. | 


HWND CreateWindow(/pClassName, IpWindowName, dwStyle, X, Y, nWidth, nHeight, 
hWndParent, hMenu, hInstance, IpParam) 


This function creates an overlapped, pop-up, or child window. The CreateWindow func- 
tion specifies the window class, window title, window style, and (optionally) initial posi- 
tion and size of the window. The CreateWindow function also specifies the window’s 
parent (if any) and menu. ; 


For overlapped, pop-up, and child windows, the CreateWindow function sends 
WM_CREATE, WM_GETMINMAXINFO, and WM_NCCREATE messages to the 
window. The /Param parameter of the WM_CREATE message contains a pointer toa 
CREATESTRUCT data structure. If WS_VISIBLE style is given, CreateWindow sends 
the window all the messages required to activate and show the window. 


If the window style specifies a title bar, the window title pointed to by the pWindowName 
parameter is displayed in the title bar. When using CreateWindow to create controls such 
as buttons, check boxes, and text controls, the Jp>WindowName parameter specifies the text 
of the control. 
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Parameter 


lpClassName 


lpWindowName 


dwStyle 


nWidth 


Type/Description 


LPSTR Points to a null-terminated character string that 
names the window class. The class name can be any name 
registered with the RegisterClass function or any of the prede- 
fined control-class names specified in Table 4.2, “Control 
Classes.” 


LPSTR Points to a null-terminated character string that repre- 
sents the window name. 


DWORD Specifies the style of window being created. It can 
be any combination of the styles given in Table 4.3, “Window 
Styles,” the control styles given in Table 4.4, “Control Styles,” 

or a combination of styles created by using the bitwise OR opera- 
tor. 


int Specifies the initial x-position of the window. For an over- 
lapped or pop-up window, the X parameter is the initial 
x-coordinate of the window’s upper-left corner (in screen coordi- 
nates). If this value is CW_USEDEFAULT, Windows selects the 
default position for the window’s upper-left corner. For a child: 
window, X is the x-coordinate of the upper-left corner of the 
window in the client area of its parent window. 


int Specifies the initial y-position of the window. For an over- 
lapped window, the Y parameter is the initial y-coordinate of the 
window’s upper-left corner. For a pop-up window, Y is the y- 
coordinate (in screen coordinates) of the upper-left corner of the 
pop-up window. For list-box controls, Y is the y-coordinate of 
the upper-left corner of the control’s client area. For a child 
window, Y is the y-coordinate of the upper-left corner of the 
child window. All of these coordinates are for the window, not 
the window’s client area. 


int Specifies the width (in device units) of the window. For 
overlapped windows, the nWidth parameter is either the 
window’s width (in screen coordinates) or CW_USEDEFAULT. 
If nWidth is CW_USEDEFAULT, Windows selects a default 
width and height for the window (the default width extends from 
the initial x-position to the right edge of the screen, and the de- 
fault height extends from the initial y-position to the top of the 
icon area). 
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Return Value 


Comments 


Parameter 


nHeight 


hWndParent 


hMenu 


hInstance 


IpParam 


CreateWindow 


Type/Description 


int Specifies the height (in device units) of the window. For 


‘overlapped windows, the nHeight parameter is the window’s 


height in screen coordinates. If the nWidth parameter is 
CW_USEDEFAULT, Windows ignores nHeight. 


HWND Identifies the parent or owner window of the window 
being created. A valid window handle must be supplied when 
creating a child window or an owned window. An owned 
window is an overlapped window that is destroyed when its 
owner window is destroyed, hidden when its owner is made 
iconic, and which is always displayed on top of its owner 
window. For pop-up windows, a handle can be supplied, but is 
not required. If the window does not have a parent or is not 
owned by another window, the hWndParent parameter must be 
set to NULL. 


HMENU Identifies a menu or a child-window identifier. The 
meaning depends on the window style. For overlapped or pop- 
up windows, the hMenu parameter identifies the menu to be 
used with the window. It can be NULL, if the class menu is to be 
used. For child windows, hMenu specifies the child-window 
identifier, an integer value that is used by a dialog-box control to 
notify its parent of events (such as the EN_HSCROLL message). 
The child-window identifier is determined by the application 
and should be unique for all child windows with the same parent 
window. 


HANDLE Identifies the instance of the module to be as- 
sociated with the window. 


LPSTR Points to a value that is passed to the window through 
the CREATESTRUCT data structure referenced by the /Param 
parameter of the WM_CREATE message. If an application is 
calling CreateWindow to create a multiple document interface 
(MDI) client window, /pParam must point to a CLIENT- 
CREATESTRUCT data structure. 


The return value identifies the new window. It is NULL if the window is not created. 


For overlapped windows where the X parameter is CW_USEDEFAULT, the Y parameter 
can be one of the show-style parameters described with the ShowWindow function, or, for 
the first overlapped window to be created by the application, it can be the nCmdShow para- 
meter passed to the WinMain function. 
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Table 4.2 lists the window control classes; Table 4.3 lists the window styles; Table 4.4 lists 
the control styles: 


Table 4.2 Control Classes 


Class Meaning 


BUTTON Designates a small rectangular child window that represents a button 
the user can turn on or off by clicking it. Button controls can be used 
alone or in groups, and can either be labeled or appear without text. But- 
ton controls typically change appearance when the user clicks them. 


COMBOBOX Designates a control consisting of a selection field similar to an edit 
control plus a list box. The list box may be displayed at all times or may 
be dropped down when the user selects a “pop box” next to the selec- 
tion field. 


Depending on the style of the combo box, the user can or cannot edit 
the contents of the selection field. If the list box is visible, typing 
characters into the selection box will cause the first list box entry that 
matches the characters typed to be highlighted. Conversely, selecting an 
item in the list box displays the selected text in the selection field. 


EDIT Designates a rectangular child window in which the user can enter text 
from the keyboard. The user selects the control, and gives it the input 
focus by clicking it or moving to it by using the TAB key. The user can 
enter text when the control displays a flashing caret. The mouse can be 
used to move the cursor and select characters to be replaced, or to posi- 
tion the cursor for inserting characters. The BACKSPACE key can be used 
to delete characters. 


Edit controls use the variable-pitch system font and display ANSI 
characters. Applications compiled to run with previous versions of 
Windows display text with a fixed-pitch system font unless they have 
been marked by the Windows 3.0 MARK utility with the MEMORY 
FONT option. An application can also send the WM_SETFONT 
message to the edit control to change the default font. 
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Table 4.2 Control Classes (continued) 


Class Meaning 


Edit controls expand tab characters into as many 
space characters as are required to move the cursor 
to the next tab stop. Tab stops are assumed to be at 
every eighth character position. 


LISTBOX Designates a list of character strings. This control 
is used whenever an application needs to present a 
list of names, such as filenames, that the user can 
view and select. The user can select a string by 
pointing to it and clicking. When a string is 
selected, it is highlighted and a notification 
message is passed to the parent window. A vertical 
or horizontal scroll bar can be used with a list-box 
control to scroll lists that are too long for the con- 
trol window. The list box automatically hides or 
shows the scroll bar as needed. 


MDICLIENT Designates an MDI client window. The MDI client 
window receives messages which control the MDI 

application’s child windows. The recommended 
style bits are WS_CLIPCHILDREN and 
WS_CHILD. To create a scrollable MDI client 
window which allows the user to scroll MDI child 
windows into view, an application can also use the 
WS_HSCROLL and WS_VSCROLL styles. 


SCROLLBAR Designates a rectangle that contains a thumb and 
has direction arrows at both ends. The scroll bar 
sends a notification message to its parent window 
whenever the user clicks the control. The parent 
window is responsible for updating the thumb posi- 
tion, if necessary. Scroll-bar controls have the 
same appearance and function as scroll bars used 
in ordinary windows. Unlike scroll bars, scroll-bar 
controls can be positioned anywhere in a window 
and used whenever needed to provide scrolling 
input for a window. 


The scroll-bar class also includes size-box controls. 
A size-box control is a small rectangle that the user 
can expand to change the size of the window. 


STATIC Designates a simple text field, box, or rectangle 
that can be used to label, box, or separate other 
controls. Static controls take no input and provide 
no output. 
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Table 4.3 Window Styles 


Style 


DS_LOCALEDIT 


DS_MODALFRAME 


DS_NOIDLEMSG 


DS_SYSMODAL 
WS_BORDER 
WS_CAPTION 
WS_CHILD 
WS_CHILDWINDOW 


WS_CLIPCHILDREN 


WS_CLIPSIBLINGS 


Meaning 


‘Specifies that edit controls in the dialog box will use 


memory in the application’s data segment. By default, all 
edit controls in dialog boxes use memory outside the appli- 
cation’s data segment. This feature may be suppressed by 
adding the DS_LOCALEDIT flag to the STYLE command 
for the dialog box. If this flag is not used, 
EM_GETHANDLE and EM_SETHANDLE messages 
must not be used since the storage for the control is not in 
the application’s data segment. This feature does not affect 
edit controls created outside of dialog boxes. 


Creates a dialog box with a modal dialog-box frame that 
can be combined with a title bar and System menu by 
specifying the WS_CAPTION and WS_SYSMENU styles. 


Suppresses WM_ENTERIDLE messages that Windows 
would otherwise send to the owner of the dialog box while 
the dialog box is displayed. 


Creates a system-modal dialog box. 
Creates a window that has a border. 


Creates a window that has a title bar (implies the 
WS_BORDER style). This style cannot be used with the 
WS_DLGFRAME style. 


Creates a child window. Cannot be used with the 
WS_POPUP style. 


Creates a child window that has the WS_CHILD style. 


Excludes the area occupied by child windows when draw- 
ing within the parent window. Used when creating the 
parent window. 


Clips child windows relative to each other; that is, when a 
particular child window receives a paint message, the 
WS_CLIPSIBLINGS style clips all other overlapped child 
windows out of the region of the child window to be up- 
dated. (If WS_CLIPSIBLINGS is not given and child 
windows overlap, it is possible, when drawing within the 
client area of a child window, to draw within the client area 
of a neighboring child window.) For use with the 
WS_CHILD style only. 
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Table 4.3 


Style 


—e 

_WS_DISABLED 
WS_DLGFRAME 
WS_GROUP 


WS_HSCROLL 
WS_ICONIC 


WS_MAXIMIZE > 
WS_MAXIMIZEBOX 
WS_MINIMIZE 
WS_MINIMIZEBOX 
WS_OVERLAPPED 


WS_OVERLAPPEDWINDOW 


WS_POPUP 


WS_POPUPWINDOW 


WS_SYSMENU 


WS_TABSTOP 


Window Styles (continued) 


Meaning 


Creates a window that is initially disabled. 
Creates a window with a double border but no title. 


Specifies the first control of a group of controls in 
which the user can move from one control to the 
next by using the DIRECTION keys. All controls de- 
fined with the WS_GROUP style after the first 
control belong to the same group. The next control 
with the WS_GROUP style ends the style group 
and starts the next group (that is, one group ends 
where the next begins). Only dialog boxes use this 
style. 


Creates a window that has a horizontal scroll bar. 


Creates a window that is initially iconic. For use 
with the WS_OVERLAPPED style only. 


Creates a window of maximum size. 
Creates a window that has a maximize box. 
Creates a window of minimum size. 
Creates a window that has a minimize box. 


Creates an overlapped window. An overlapped 
window has a caption and a border. 


Creates an overlapped window having the 
WS_OVERLAPPED, WS_CAPTION, WS_SYS- 
MENU, WS_THICKFRAME, 
WS_MINIMIZEBOX, and WS_MAXIMIZEBOX 
styles. 


Creates a pop-up window. Cannot be used with the 
WS_CHILD style. 


Creates a pop-up window that has the 
WS_BORDER, WS_POPUP, and WS_SYS- 
MENU styles. The WS_CAPTION style must be 
combined with the WS_POPUPWINDOW style to 
make the system menu visible. 


Creates a window that has a System-menu box in 
its title bar. Used only for windows with title bars. 


Specifies one of any number of controls through 
which the user can move by using the TAB key. The 
TAB key moves the user to the next control 
specified by the WS_TABSTOP style. Only dialog 
boxes use this style. 
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Table 4.3 Window Styles (continued) 


Style 


WS_THICKFRAME 
WS_VISIBLE 
WS_VSCROLL 


Table 4.4 Control Styles 
Style 
BUTTON Class 


BS_AUTOCHECKBOX 
BS_AUTORADIOBUTTON 
BS_AUTO3STATE 
BS_CHECKBOX 


BS_DEFPUSHBUTTON 


BS_GROUPBOX 


BS_LEFTTEXT 


e 


Meaning 


Creates a window with a thick frame that can be 
used to size the window. 


Creates a window that is initially visible. This ap- 
plies to overlapped and pop-up windows. For 
overlapped windows, the Y parameter is used as a 
Show Window function parameter. 


Creates a window that has a vertical scroll bar. 


Meaning 


Identical to BS_CHECKBOX, except that the but- 
ton automatically toggles its state whenever the 
user Clicks it. 


Identical to BS_RADIOBUTTON, except that the 
button is checked, the application is notified by 
BN_CLICKED, and the checkmarks are removed 
from all other radio buttons in the group. 


Identical to BS_3STATE, except that the button au- 
tomatically toggles its state when the user clicks it. 


Designates a small rectangular button that may be 
checked; its border is bold when the user clicks the 
button. Any text appears to the right of the button. 


Designates a button with a bold border. This button 
represents the default user response. Any text is dis- 
played within the button. Windows sends a 
message to the parent window when the user clicks 
the button. 


Designates a rectangle into which other buttons are 
grouped. Any text is displayed in the rectangle’s 
upper-left corner. 


Causes text to appear on the left side of the radio 
button or check-box button. Use this style with the 
BS_CHECKBOX, BS_RADIOBUTTON, or 
BS_3STATE styles. 
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Table 4.4 Control Styles (continued) 


Style 


BS_OWNERDRAW 


BS_PUSHBUTTON 


BS_RADIOBUTTON 


BS_3STATE 


COMBOBOX Class 


CBS_AUTOHSCROLL 


CBS_DROPDOWN 


CBS_DROPDOWNLIST 


CBS_HASSTRINGS 


Meaning 


Designates an owner-draw button. The parent 
window is notified when the button is clicked. 
Notification includes a request to paint, invert, and 
disable the button. 


Designates a button that contains the given text. 
The control sends a message to its parent window 
whenever the user clicks the button. 


Designates a small circular button that can be 
checked; its border is bold when the user clicks the 
button. Any text appears to the right of the button. 
Typically, two or more radio buttons are grouped 
together to represent mutually exclusive choices, 
so no more than one button in the group is checked 
at any time. 


Identical to BS_CHECKBOxX, except that a button 
can be grayed as well as checked. The grayed state 
typically is used to show that a check box has been 
disabled. 


Automatically scrolls the text in the edit control to 
the right when the user types a character at the end 
of the line. If this style is not set, only text which 
fits within the rectangular boundary is allowed. 


Similar to CBS_SIMPLE, except that the list box 
is not displayed unless the user selects an icon next 
to the selection field. 


Similar to CBS_DROPDOWN, except that the edit 
control is replaced by a static text item which dis- 
plays the current selection in the list box. 


An owner-draw combo box contains items con- 
sisting of strings. The combo box maintains the 
memory and pointers for the strings so the applica- 
tion can use the LB_GETTEXT message to 
retrieve the text for a particular item. 
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Table 4.4 Control Styles (continued) 


Style 


CBS_OEMCONVERT 


CBS_OWNERDRAWFIXED 


CBS_OWNERDRAWVARIABLE 


CBS_SIMPLE 


CBS_SORT 


EDIT Class 


ES_AUTOHSCROLL 


ES_AUTOVSCROLL 


ES_CENTER 
ES_LEFT 
ES_LOWERCASE 


ES_MULTILINE 


Meaning 


Text entered in the combo box edit control is con- 
verted from the ANSI character set to the OEM 
character set and then back to ANSI. This ensures 
proper character conversion when the application 
calls the AnsiToOem function to convert an ANSI 
string in the combo box to OEM characters. This 
style is most useful for combo boxes that contain 
filenames and applies only to combo boxes created 
with the CBS_SIMPLE or CBS_DROPDOWN 
styles. 


The owner of the list box is responsible for draw- 
ing its contents; the items in the list box are all the 
same height. 


The owner of the list box is responsible for draw-- 
ing its contents; the items in the list box are 
variable in height. 


The list box is displayed at all times. The current 
selection in the list box is displayed in the edit con- 
trol. 


Automatically sorts strings entered into the list 
box. 


Automatically scrolls text to the right by 10 
characters when the user types a character at the 
end of the line. When the user presses the ENTER 
key, the control scrolls all text back to position 
zero. 


Automatically scrolls text up one page when the 
user presses ENTER on the last line. 


Centers text in a multiline edit control. 
Aligns text flush-left. 


Converts all characters to lowercase as they are 
typed into the edit control. 


Designates multiple-line edit control. (The default _ 
is single-line.) If the Es_AUTOVSCROLL style is 
specified, the edit control shows as many lines as 
possible and scrolls vertically when the user 

presses the ENTER key. If ES_AUTOVSCROLL is 
not given, the edit control shows as many lines as 
possible and beeps if ENTER is pressed when no 
more lines can be displayed. 
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Table 4.4 Control Styles (continued) 


Style 


ES_NOHIDESEL 


ES_OEMCONVERT 


ES_PASSWORD 


ES_RIGHT 


ES_UPPERCASE 


LISTBOX Class 


LBS_EXTENDEDSEL 


Meaning 


If the ES_AUTOHSCROLL style is specified, the 
multiple-line edit control automatically scrolls hori- 
zontally when the caret goes past the right edge of 
the control. To start a new line, the user must press 
ENTER. If ES_AUTOHSCROLL is not given, the 
control automatically wraps words to the begin- 
ning of the next line when necessary; a new line is 
also started if ENTER is pressed. The position of the 
wordwrap is determined by the window size. If the 
window size changes, the wordwrap position 
changes, and the text is redisplayed. 


Multiple-line edit controls can have scroll bars. An 
edit control with scroll bars processes its own 
scroll-bar messages. Edit controls without scroll 
bars scroll as described above, and process any 
scroll messages sent by the parent window. 


Normally, an edit control hides the selection when 
the control loses the input focus, and inverts the 
selection when the control receives the input focus. 
Specifying ES_NOHIDESEL deletes this default 
action. 


Text entered in the edit control is converted from 
the ANSI character set to the OEM character set 
and then back to ANSI. This ensures proper 
character conversion when the application calls the 
AnsiToOem function to convert an ANSI string in 
the edit control to OEM characters. This style is 
most useful for edit controls that contain filenames. 


Displays all characters as an asterisk (*) as they are 
typed into the edit control. An application can use 
the EM_SETPASSWORDCHAR message to 
change the character that is displayed. 


Aligns text flush-right in a multiline edit control. 


Converts all characters to uppercase as they are 
typed into the edit control. 


The user can select multiple items using the SHIFT 
key and the mouse or special key combinations. 
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Table 4.4 Control Styles (continued) 


Style 


LBS_HASSTRINGS 


LBS_MULTICOLUMN 


LBS_MULTIPLESEL 


LBS_NOINTEGRALHEIGHT 


LBS_NOREDRAW 


LBS_NOTIFY 


LBS_OWNERDRAWFIXED 


LBS_OWNERDRAWVARIABLE 


LBS_SORT 
LBS_STANDARD 


LBS_USETABSTOPS 


Meaning 


Specifies an owner-draw list box which contains 
items. consisting of strings. The list box maintains 
the memory and pointers for the strings so the 
application can use the LB_GETTEXT message to 
retrieve the text for a particular item. 


Specifies a multicolumn list box that is scrolled 
horizontally. The LB_SETCOLUMNWIDTH 
message sets the width of the columns. 


String selection is toggled each time the user clicks 
or double-clicks the string. Any number of strings 
can be selected. 


The size of the list box is exactly the size specified 
by the application when it created the list box. Nor- 
mally, Windows sizes a list box so that the list box 
does not display partial items. 


List-box display is not updated when changes are 
made. This style can be changed at any time by 
sending a WM_SETREDRAW message. 


Parent window receives an input message when- 
ever the user clicks or double-clicks a string. 


The owner of the list box is responsible for draw- 
ing its contents; the items in the list box are the 
same height. 


The owner of the list box is responsible for draw- 
ing its contents; the items in the list box are 
variable in height. 


Strings in the list box are sorted alphabetically. 


Strings in the list box are sorted alphabetically and 
the parent window receives an input message 
whenever the user clicks or double-clicks a string. 
The list box contains borders on all sides. 


Allows a list box to recognize and expand tab 
characters when drawing its strings. The default 
tab positions are 32 dialog units. (A dialog unit is a 
horizontal or vertical distance. One horizontal 
dialog unit is equal to 1% of the current dialog base 
width unit. The dialog base units are computed 
based on the height and width of the current sys- 
tem font. The GetDialogBaseUnits function 
returns the current dialog base units in pixels.) 
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Table 4.4 Control Styles (continued) 


Style 


LBS_WANTKEYBOARDINPUT 


SCROLLBAR Class 


SBS_BOTTOMALIGN 


SBS_HORZ 


SBS_LEFTALIGN 


SBS_RIGHTALIGN 


SBS_SIZEBOX 


SBS_SIZEBOXBOTTOMRIGHTALIGN 


Meaning 


The owner of the list box receives WM_VKEY- 
TOITEM or WM_CHARTOITEM messages 
whenever the user presses a key when the list box 
has input focus. This allows an application to per- 
form special processing on the keyboard input. 


Used with the SBS_HORZ style. The bottom edge 
of the scroll bar is aligned with the bottom edge of 
the rectangle specified by the X, Y, nWidth, and 
nHeight parameters given in the CreateWindow 
function. The scroll bar has the default height for 
system scroll bars. 


Designates a horizontal scroll bar. If neither the 
SBS_BOTTOMALIGN nor SBS_TOPALIGN 
style is specified, the scroll bar has the height, 
width, and position given in the CreateWindow 
function. 


Used with the SBS_VERT style. The left edge of 
the scroll bar is aligned with the left edge of the 
rectangle specified by the X, Y, nWidth, and 
nHeight parameters given in the CreateWindow 
function. The scroll bar has the default width for 
system scroll bars. 


Used with the SBS_VERT style. The right edge of 
the scroll bar is aligned with the right edge of the 
rectangle specified by the X, Y, nWidth, and 
nHeight parameters given in the CreateWindow 
function. The scroll bar has the default width for 
system scroll bars. 


Designates a size box. If neither the SBS_SIZE- 
BOXBOTTOMRIGHTALIGN nor 
SBS_SIZEBOXTOPLEFTALIGN style is 
specified, the size box has the height, width, and 
position given in the CreateWindow function. 


Used with the SBS_SIZEBOX style. The lower- 
right comer of the size box is aligned with the 
lower-right comer of the rectangle specified by the 
X,Y, nWidth, and nHeight parameters given in the 
CreateWindow function. The size box has the de- 
fault size for system size boxes. 


CreateWindow 


Table 4.4 
Style 


SBS_SIZEBOXTOPLEFTALIGN 


SBS_TOPALIGN 


SBS_VERT 
STATIC Class 
SS_BLACKFRAME 
SS_BLACKRECT 


SS_CENTER 


SS_GRAYFRAME 
SS_GRAYRECT 


SS_ICON 
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Control Styles (continued) 


Meaning 


Used with the SBS_SIZEBOX style. The upper- 
left comer of the size box is aligned with the 
upper-left corner of the rectangle specified by the 
X, Y, nWidth, and nHeight parameters given in the 
CreateWindow function. The size box has the de- 
fault size for system size boxes. 


Used with the SBS_HORZ style. The top edge of 
the scroll bar is aligned with the top edge of the 
rectangle specified by the X, Y, nWidth, and 
nHeight parameters given in the CreateWindow 
function. The scroll bar has the default height for 
system scroll bars. 


Designates a vertical scroll bar. If neither the 
SBS_RIGHTALIGN nor SBS_LEFTALIGN style 
is specified, the scroll bar has the height, width, 
and position given in the CreateWindow function. 


Specifies a box with a frame drawn with the same 
color as window frames. This color is black in the 
default Windows color scheme. 


Specifies a rectangle filled with the color used to 
draw window frames. This color is black in the de- 
fault Windows color scheme. 


Designates a simple rectangle and displays the 
given text centered in the rectangle. The text is for- 
matted before it is displayed. Words that would 
extend past the end of a line are automatically 
wrapped to the beginning of the next centered line. 


Specifies a box with a frame drawn with the same 
color as the screen background (desktop). This 
color is gray in the default Windows color scheme. 


Specifies a rectangle filled with the color used to 
fill the screen background. This color is gray in the 
default Windows color scheme. 


Designates an icon displayed in the dialog box. 
The given text is the name of an icon (not a 
filename) defined elsewhere in the resource file. 
The nWidth and nHeight parameters are ignored; 
the icon automatically sizes itself. 


4-75 


CreateWindow 


Table 4.4 Control Styles (continued) 


Style 


SS_LEFT 


SS_LEFTNOWORDWRAP 


SS_NOPREFIX 


SS_RIGHT 


SS_SIMPLE 


SS_USERITEM 
SS_WHITEFRAME 


SS_WHITERECT 


Meaning 


Designates a simple rectangle and displays the 
given text flush-left in the rectangle. The text is for- 
matted before it is displayed. Words that would 
extend past the end of a line are automatically 
wrapped to the beginning of the next flush-left 

line. 


Designates a simple rectangle and displays the 
given text flush-left in the rectangle. Tabs are ex- 
panded, but words are not wrapped. Text that 
extends past the end of a line is clipped. 


Unless this style is specified, windows will inter- 
pret any “&” characters in the control’s text to be 
accelerator prefix characters. In this case, the “&” 
is removed and the next character in the string is 
underlined. If a static control is to contain text 
where this feature is not wanted, SS_NOPREFIX 
may be added. This static-control style may be in- 
cluded with any of the defined static controls. 


You can combine SS_NOPREFIX with other 
styles by using the bitwise OR operator. This is 
most often used when filenames or other strings 
that may contain an “&” need to be displayed in a 
static control in a dialog box. 


Designates a simple rectangle and displays the 
given text flush-right in the rectangle. The text is 
formatted before it is displayed. Words that would 
extend past the end of a line are ‘automatically 
wrapped to the beginning of the next flush-right 
line. 


Designates a simple rectangle and displays a single 
line of text flush-left in the rectangle. The line of 
text cannot be shortened or altered in any way. 
(The control’s parent window or dialog box must 
not process the WM_CTLCOLOR message.) 


Specifies a user-defined item. 


Specifies a box with a frame drawn with the same 
color as window backgrounds. This color is white 
in the default Windows color scheme. 


Specifies a rectangle filled with the color used to 
fill window backgrounds. This color is white in the 
default Windows color scheme. 
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CreateWindowEx 


Syntax HWND_  CreateWindowEx(dwExStyle, lpClassName, lpWindowName, dwStyle, X, Y, 
nWidth, nHeight, hWndParent, hMenu, hInstance, lpParam) 


; ‘| This function creates an overlapped, pop-up, or child window with an extended style 

4 specified in the dwExStyle parameter. Otherwise, this function is identical to the 

' CreateWindow function. See the description of the CreateWindow function for more 
information on creating a window and for a full descriptions of the other parameters of 


CreateWindowEx. 

Parameter Type/Description 

dwExStyle DWORD _Specifies the extended style of the window being 
created. Table 4.5, “Extended Window Styles,” lists the ex- 
tended window styles. 

IpClassName LPSTR Points to a null-terminated character string that 
names the window class. 

lpWindowName LPSTR Points to a null-terminated character string that repre- 

sents the window name. 

dwStyle DWORD Specifies the style of window being created. 

Xx int Specifies the initial x-position of the window. 

Y int Specifies the initial y-position of the window. 

nWidth int Specifies the width (in device units) of the window. 

nHeight int Specifies the height (in device units) of the window. 

hWndParent HWND Identifies the parent or owner window of the window 
being created. 

hMenu HMENU Identifies a menu or a child-window identifier. The 
meaning depends on the window style. 

hInstance HANDLE Identifies the instance of the module to be as- 
sociated with the window. . 

lpParam . LPSTR Points to a value that is passed to the window through 
the CREATESTRUCT data structure referenced by the /Param 
parameter of the WM_CREATE message. 

Return Value The return value identifies the new window. It is NULL if the window is not created. 


Comments Table 4.5 lists the extended window styles. 
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Table 4.5 Extended Window Styles 
Style Meaning 


WS_EX_DLGMODALFRAME Designates a window with a double border that may op- 
tionally be created with a title bar by specifying the 
WS_CAPTION style flag in the dwStyle parameter. 


WS_EX_NOPARENTNOTIFY Specifies that a child window created with this style will 
not send the WM_PARENTNOTIFY message to its 
parent window when the child window is created or de- 
stroyed. 


Table 4.2, “Control Classes,” lists the window control classes. Table 4.3, “Window Styles,” 
lists the window styles. Table 4.4, “Control Styles,” lists the control styles. See the descrip- 
tion of the CreateWindow function for these tables. 
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DebugBreak 7 
Syntax void DebugBreak() 


This function forces a break to the debugger. 


This function has no parameters. 


Return Value None. 


DefDigProc 
Syntax LONG _ DefDigProc(hDlg, wMsg, wParam, lParam) 


This function provides default processing for any Windows messages that a dialog box 
with a private window class does not process. 


All window messages that are not explicitly processed by the window function must be 
passed to the DefDlgProc function, not the DefWindowProc function. This ensures that 
all messages not handled by their private window procedure will be handled properly. 


Parameter Type/Description 

hDlg HWND Identifies the dialog box. | 

wMseg WORD Specifies the message number. 

wParam WORD Specifies 16 bits of additional message-dependent infor- 
mation. 

lParam DWORD Specifies 32 bits of additional message-dependent infor- 
mation. 

Return Value The return value specifies the result of the message processing and depends on the actual 


message sent. 


Comments The source code for the DefDIgProc function is provided on the SDK disks. 


An application creates a dialog box by calling one of the following functions: 


Function Description 
CreateDialog Creates a modeless dialog box. 


CreateDialogIndirect Creates a modeless dialog box. 
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DeferWindowPos 


Function Description 

CreateDialogIndirectParam Creates a modeless dialog box and passes data to it 
when it is created. | 

CreateDialogParam Creates a modeless dialog box and passes data to it 
when it is created. 

DialogBox Creates a modal dialog box. 

DialogBoxIndirect Creates a modal dialog box. 

DialogBoxIndirectParam Creates a modal dialog box and passes data to it 
when it is created. 

DialogBoxParam Creates a modal dialog box and passes data to it 


DeferWindowPos 
HANDLE = DeferWindowPos(iWinPosInfo, hWnd, hWndInsertAfter, x, y, CX, Cy, 


Syntax 


wF lags) 


when it is created. 


This function updates the multiple window-position data structure identified by the hWin- 
PosInfo parameter for the window identified by hWnd parameter and returns the handle of 
the updated structure. The EndDeferWindowPos function uses the information in this 
structure to change the position and size of a number of windows simultaneously. The 
BeginDeferWindowPos function creates the multiple window-position data structure used 


by this function. 


The x and y parameters specify the new position of the window, and the cx and cy para- 
meters specify the new size of the window. 


Parameter 


hWinPosInfo 


hWnd 


hWndInsertAfter 


Type/Description 


HANDLE Identifies a multiple window-position data struc- 
ture that contains size and position information for one or more 
windows. This structure is returned by the BeginDeferWindow- 
Pos function or the most recent call to the Defer WindowPos 
function. 


HWND Identifies the window for which update information 
is to be stored in the data structure. 


HWND Identifies the window following which the window 
identified by the hWnd parameter is to be updated. 
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Return Value 


Parameter ~ Type/Description 
x int Specifies the x-coordinate of the window’s upper-left 
- corner. 
y int | Specifies the y-coordinate of the window’s upper-left 
corner. 
cx int Specifies the window’s new width. 
cy int Specifies the window’s new height. 
wF lags WORD Specifies one of eight possible 16-bit values that af- 


fect the size and position of the window. It must be one of the 
following values: 


Value Meaning 


SWP_DRAWFRAME Draws a frame (defined in the 
window’s class description) 
around the window. 


SWP_HIDEWINDOW Hides the window. 
SWP_NOACTIVATE Does not activate the 
window. 
SWP_NOMOVE Retains current position (ig- 
nores the x and y parameters). 
SWP_NOREDRAW Does not redraw changes. 
SWP_NOSIZE Retains current size (ignores 
the cx and cy parameters). 
SWP_NOZORDER Retains current ordering (ig- 
nores the hWndInsertAfter 
parameter). 
SWP_SHOWWINDOW Displays the window. 


The return value identifies the updated multiple window-position data structure. The 
handle returned by this function may differ from the handle passed to the function as the 
hWinPosInfo parameter. The new handle returned by this function should be passed to the 
next call to DeferWindowPos or the EndDeferWindowPos function. 


The return value is NULL if insufficient system resources are available for the function to 
complete successfully. 
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Comments 


DefFrameProc 
Syntax 


Return Value 


Comments 


DefFrameProc 


If the SWP_NOZORDER flag is not specified, Windows places the window identified by 
the hWnd parameter in the position following the window identified by the hWndInser- 

tAfter parameter. If hWndInsertAfter is NULL, Windows places the window identified by 
hWnd at the top of the list. If hWndInsertAfter is set to 1, Windows places the window iden- 
tified by hWnd at the bottom of the list. 


If the SWP_SHOWWINDOW or the SWP_HIDEWINDOW flags are set, scrolling and 
moving cannot be done simultaneously. 


All coordinates for child windows are relative to the upper-left comer of the parent 
window’s client area. 


LONG | DefFrameProc(hWnd, hWndMDIClient, wMsg, wParam, lParam) 


This function provides default processing for any Windows messages that the window 
function of a multiple document interface (MDI) frame window does not process. All 
window messages that are not explicitly processed by the window function must be passed 
to the DefFrameProc function, not the DefWindowProc function. 


Parameter Type/Description 

hWnd HWND Identifies the MDI frame window. 

hWndMDiIClient HWND Identifies the MDI client window. 

wMseg WORD Specifies the message number. 

wParam WORD Specifies 16 bits of additional message-dependent 

information. 

lParam DWORD Specifies 32 bits of additional message-dependent 

. information. 


The return value specifies the result of the message processing and depends on the actual 
message sent. If the hWndMDIClient parameter is NULL, the return value is the same as 
for the DefWindowProc function. 


Normally, when an application’s window procedure does not handle a message, it passes 
the message to the DefWindowProc function, which processes the message. MDI applica- 
tions use the DefFrameProc and DefMDIChildProc functions instead of DefWindow- 
Proc to provide default message processing. All messages that an application would 
normally pass to DefWindowProc (such as nonclient messages and WM_SETTEXT) 
should be passed to DefFrameProc instead. In addition to these, DefFrameProc also han- 
dles the following messages: 


DefHookProc 
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Message 


WM_COMMAND 


WM_MENUCHAR 
WM_NEXTMENU 
WM_SETFOCUS 


WM_SIZE 


Default Processing by DefFrameProc 


The frame window of an MDI application receives the 
WM_COMMAND message to activate a particular MDI 
child window. The window ID accompanying this message 
will be the ID of the MDI child window assigned by 
Windows, starting with the first ID specified by the applica- 
tion when it created the MDI client window. This value of 
the first ID must not conflict with menu-item IDs. 


When the ALT+HYPHEN key is pressed, the control menu of 
the active MDI child window will be selected. 


This message causes the control menu of the active MDI 
child window to be selected. 


DefFrameProc passes focus on to the MDI client, which in 
turn passes the focus on to the active MDI child window. 


If the frame window procedure passes this message to Def- 
FrameProc, the MDI client window will be resized to fit in 
the new client area. If the frame window procedure sizes the 
MDI client to a different size, it should not pass the message 
to DefWindowProc. 


DefHookProc 
DWORD  DefHookProc(code, wParam, !Param, IplpfnNextHook) 


Syntax 


This function calls the next function in a chain of hook functions. A hook function is a 
function that processes events before they are sent to an application’s message-processing 
loop in the WinMain function. When an application defines more than one hook function 
by using the SetWindowsHook function, Windows forms a linked list or hook chain. 
Windows places functions of the same type in a chain. 


Parameter 


code 


wParam 


[Param 


Type/Description 


int Specifies a code used by the Windows hook function (also 
called the message filter function) to determine how to process 
the message. 


WORD _ Specifies the word parameter of the message that the 
hook function is processing. 


DWORD Specifies the long parameter of the message that the 
hook function is processing. 
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Parameter Type/Description 


lplpfnNextHook FARPROC FAR * Points to a memory location that contains 
the FARPROC structure returned by the SetWindowsHook 
function. Windows changes the value at this location after an 
application calls the UnhookWindowsHook function. 


Return Value The return value specifies a value that is directly related to the code parameter. 


DefineHandleTable 
Syntax BOOL _ DefineHandleTable(wOffset) 


This function creates a private handle table in an application’s default data segment. The 
application stores in the table the segment addresses of global memory objects returned by 
the GlobalLock function. In real mode, Windows updates the corresponding address in the 
private handle table when it moves a global memory object. When Windows discards an 
object with a corresponding table entry, Windows replaces the address of the object in the 
table with the object’s handle. Windows does not update addresses in the private handle 
table in protected (standard or 386 enhanced) mode. 


Parameter Type/Description 


wOffset WORD Specifies the offset from the beginning of the data 
segment to the beginning of the private handle table. If wOffset 
is zero, Windows no longer updates the private handle table. 


Return Value The return value is nonzero if the function was successful. Otherwise, it is zero. 
Comments The private handle table has the following format: 

Count 

Clear_Number 


Entry[@] 


Entry[Count-1] 


The firsts WORD (Count) in the table specifies the number of entries in the table. The sec- 
ond WORD (Clear_Number) specifies the number of entries (from the beginning of the 
table) which Windows will set to zero when Windows updates its least-recently-used 
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(LRU) memory list. The remainder of the table consists of an array of addresses returned 
by GlobalLock. 


The application must initialize the Count field in the table before calling DefineHandle- 
Table. The application can change either the Count or Clearn_Number fields at any time. 


DefMDIChildProc 
Syntax LONG DefMDIChildProc(hWnd, wMsg, wParam, lParam) 


This function provides default processing for any Windows messages that the window 
function of a multiple document interface (MDI) child window does not process. All 
window messages that are not explicitly processed by the window function must be passed 
to the DefMDIChildProc function, not the DefWindowProc function. 


Parameter Type/Description 

hWnd ~  HWND Identifies the MDI child window. 

wMsg WORD _ Specifies the message number. 

wParam WORD Specifies 16 bits of additional message-dependent infor- 
mation. 

IParam DWORD Specifies 32 bits of additional message-dependent infor- 
mation. 

Return Value The return value specifies the result of the message processing and depends on the actual 


message sent. 


Comments This function assumes that the parent of the window identified by the hWnd parameter was 
created with the MDICLIENT class. 


Normally, when an application’s window procedure does not handle a message, it passes 
the message to the DefWindowProc function, which processes the message. MDI applica- 
tions use the DefFrameProc and DefMDIChildProc functions instead of DefWindow- 
Proc to provide default message processing. All messages that an application would 
normally pass to DefWindowProc (such as nonclient messages and WM_SETTEXT) 
should be passed to DefMDIChildProc instead. In addition to these, DefMDIChildProc 
also handles the following messages: 
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Message Default Processing by DefMDIChildProc 
WM_CHILDACTIVATE Performs activation processing when child windows 

are sized, moved, or shown. This message must be 
passed. 

WM_GETMINMAXINFO Calculates the size of a maximized MDI child 
window based on the current size of the MDI client 
window. 

WM_MENUCHAR Sends the key to the frame window. 

WM_MOVE Recalculates MDI client scroll bars, if they are pre- 
sent. 

WM_NEXTMENU Wraps back to the frame menu bar or frame control 
menu. 

WM_SETFOCUS Activates the child window if it is not the active 
MDI child. 

WM_SIZE Performs necessary operations when changing the 
size of a window, especially when maximizing or re- 
storing an MDI child window. Failing to pass this 
message to DefMDIChildProc will produce highly 
undesirable results. 

WM_SYSCOMMAND Also handles the “next window” command. 

DefWindowProc 

Syntax LONG DefWindowProc(iWnd, wMsg, wParam, lParam) 


This function provides default processing for any Windows messages that a given applica- 
tion does not process. All window messages that are not explicitly processed by the class 
window function must be passed to the DefWindowProc function. 


Parameter Type/Description 

hWnd HWND Identifies the window that passes the message. 

wMsg WORD _ Specifies the message number. 

wParam WORD _ Specifies 16 bits of additional message-dependent infor- 


mation. 
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Parameter Type/Description 
lParam DWORD _ Specifies 32 bits of additional message-dependent infor- 
mation. 
_ Return Value The return value specifies the result of the message processing and depends on the actual 


message sent. 


Comments The source code for the DefWindowProc function is provided on the SDK disks. 
DeleteAtom 
Syntax ATOM _ DeleteAtom(nAtom) 


This function deletes an atom and, if the atom’s reference count is zero, removes the as- 
sociated string from the atom table. 


An atom’s reference count specifies the number of times the atom has been added to the 

‘atom table. The AddAtom function increases the count on each call; the DeleteAtom func- 
tion decreases the count on each call. DeleteAtom removes the string only if the atom’s 
reference count is zero. 


Parameter Type/Description 
nAtom ATOM Identifies the atom and character string to be deleted. 
Return Value The return value specifies the outcome of the function. It is NULL if the function is 


successful. It is equal to the nAtom parameter if the function failed and the atom has not 
been deleted. 


DeleteDC 
Syntax BOOL DeleteDC(hDC) 


This function deletes the specified device context. If the DC parameter is the last device 
context for a given device, the device is notified and all storage and system resources used 
by the device are released. 


Parameter Type/Description 


hDC HDC Identifies the device context. 
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Return Value The return value specifies whether the device context is deleted. It is nonzero if the device 
context is successfully deleted (regardless of whether the deleted device context is the last 
context for the device). If an error occurs, the return value is zero. 


Comments An application must not delete a device context whose handle was obtained by calling the 
GetDC function. Instead, it must call the ReleaseDC function to free the device context. 


DeleteMenu 


Syntax BOOL DeleteMenu(/Menu, nPosition, wF lags) 


This function deletes an item from the menu identified by the Menu parameter; if the 
menu item has an associated pop-up menu, DeleteMenu destroys the handle by the pop-up 
menu and frees the memory used by the pop-up menu. 


Parameter Type/Description 
hMenu HMENU Identifies the menu to be changed. 
nPosition WORD Specifies the menu item which is to be deleted. If wFlags 


is setto MF_BYPOSITION, nPosition specifies the position of the 
menu item; the first item in the menu is at position 0. If wFlags is set 
to MF_BYCOMMAND, then nPosition specifies the command ID of 
the existing menu item. 


wF lags WORD Specifies how the nPosition parameter is interpreted. It 
may be set to either MF_BYCOMMAND (the default) or MF_BY- 
POSITION. 
Return Value The return value specifies the outcome of the function. It is TRUE if the function is 


successful. Otherwise, it is FALSE. 


Comments Whenever a menu changes (whether or not the menu resides in a window that is dis- 
played), the application should call DrawMenuBar. 


DeleteMetaFile 
Syntax BOOL DeleteMetaFile(AMF) 


This function deletes access to a metafile by freeing the system resources associated with 
that metafile. It does not destroy the metafile itself, but it invalidates the metafile handle, 
hMF. Access to the metafile can be reestablished by retrieving a new handle by using the 
GetMetaFile function. 
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Return Value 


DeleteObject 
Syntax 


Return Value 


Comments 


DestroyCaret 
Syntax 


Parameter Type/Description 


hMF HANDLE Identifies the metafile to be deleted. 


The return value specifies whether the metafile handle is invalidated. It is nonzero if the 
metafile’s system resources are deleted. It is zero if the hMF parameter is not a valid 
handle. 


BOOL DeleteObject(hObject) 


This function deletes a logical pen, brush, font, bitmap, region, or palette from memory by 
freeing all system storage associated with the object. After the object is deleted, the hOb- 
ject handle is no longer valid. 


Parameter Type/Description 


hObject HANDLE Identifies a handle to a logical pen, brush, font, bitmap, 
region, or palette. 


The return value specifies whether the specified object is deleted. It is nonzero if the object 
is deleted. It is zero if the hObject parameter is not a valid handle or is currently selected 
into a device context. 


The object to be deleted should not be currently selected into a device context. 


When a pattern brush is deleted, the bitmap associated with the brush is not deleted. The 
bitmap must be deleted independently. 


An application must not delete a stock object. 


void DestroyCaret( ) 


This function destroys the current caret shape, frees the caret from the window that cur- 
rently owns it, and removes the caret from the screen if it is visible. The DestroyCaret 
function checks the ownership of the caret and destroys the caret only if a window in the 
current task owns it. 
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DestroyCursor 


Return Value 


Comments 


DestroyCursor 
Syntax 


Return Value 


If the caret shape was previously a bitmap, DestroyCaret does not free the bitmap. 


This function has no parameters. 
None. 


The caret is a shared resource. If a window has created a caret shape, it destroys that shape 
before it loses the input focus or becomes inactive. 


BOOL _ DestroyCursor(hCursor) 


This function destroys a cursor that was previously created by the CreateCursor function 
and frees any memory that the cursor occupied. It should not be used to destroy any cursor 
that was not created with the CreateCursor function. 


Parameter Type/Description 


hCursor HCURSOR Identifies the cursor to be destroyed. The 
cursor must not be in current use. 


The return value is nonzero if the function was successful. It is zero if the function failed. 


Destroylcon 


Syntax 


Return Value 


BOOL _ DestroyIcon(h/con) 


This function destroys an icon that was previously created by the CreateIcon function and 
frees any memory that the icon occupied. It should not be used to destroy any icon that 
was not created with the CreateIcon function. 


Parameter Type/Description 


hIcon HICON Identifies the icon to be destroyed. The icon must 
not be in current use. 


The return value is nonzero if the function was successful. It is zero if the function failed. 
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DestroyMenu 
Syntax 


Return Value 


BOOL DestroyMenu(iMenu) 


This function destroys the menu specified by the hMenu parameter and frees any memory 
that the menu occupied. 


Parameter Type/Description 


hMenu HMENU Identifies the menu to be destroyed. 


The return value specifies whether or not the specified menu is destroyed. It is nonzero if 
the menu is destroyed. Otherwise, it is zero. 


DestroyWindow 


Syntax 


Return Value 


BOOL DestroyWindow(hWnd) 


This function destroys the specified window. The DestroyWindow function hides or per- 
manently closes the window, sending the appropriate messages to the window to deacti- 
vate it and remove the input focus. It also destroys the window menu, flushes the 
application queue, destroys outstanding timers, removes clipboard ownership, and breaks 
the clipboard-viewer chain, if the window is at the top of the viewer chain. It sends 
WM_DESTROY and WM_NCDESTROY messages to the window. 


If the given window is the parent of any windows, these child windows are automatically 
destroyed when the parent window is destroyed. DestroyWindow destroys child windows 
first, and then the window itself. . 


Destroy Window also destroys modeless dialog boxes created by the CreateDialog func- 
tion. 


Parameter Type/Description 


hWnd . HWND Identifies the window to be destroyed. 


The return value specifies whether or not the specified window is destroyed. It is nonzero 
if the window is destroyed. Otherwise, it is zero. , 
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DeviceCapabilities 
DWORD _ DeviceCapabilities(/pDeviceName, lpPort, nIndex, IlpOutput, IpDevMode) 


Syntax 


DeviceCapabilities 


This function retrieves the capabilities of the printer device driver. 


Parameter 


IpDeviceName 


[pPort 


nIndex 


Type/Description 


LPSTR Points to a null-terminated character string that con- 
tains the name of the printer device, such as “PCL/HP LaserJet.” 


LPSTR Points to a null-terminated character string that con- 
tains the name of the port to which the device is connected, such 


as LPT1:. 


WORD _ Specifies the capabilities to query. It can be any one of 


the following values: 


Value 


DC_BINNAMES 


DC_BINS 


Meaning 


Copies a structure identical to that re- 
turned by the ENUMPAPERBINS 
escape. A printer driver does not need 
to support this index if it has only 
bins corresponding to predefined in- 
dexes, in which case no data is 
copied and the return value is 0. If 
the index is supported, the return 
value is the number of bins copied. If 
IpOutput is NULL, the return value is 
the number of bin entries required. 


Retrieves a list of available bins. The 
function copies the list to IpOutput as 
a WORD array. If /pOutput is 
NULL, the function returns the num- 
ber of supported bins to allow the 
application the opportunity to allo- 
cate a buffer with the correct size. 
See the description of the dmDefault- 
Source field of the DEVMODE 
data structure for information on 
these values. An application can de- 
termine the name of device-specific 
bins by using the ENUMPAPER- 
BINS escape. 


DeviceCapabilities 


Parameter 


Type/Description 


Value 


DC_DRIVER 


DC_DUPLEX 
DC_EXTRA 


DC_FIELDS 


DC_MAXEXTENT 


DC_MINEXTENT 
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Meaning 


Returns the printer driver version 
number. 


Returns the level of duplex support. 
The function returns 1 if the printer is 
capable of duplex printing. Other- 
wise, the return value is zero. 


Returns the number of bytes required 
for the device-specific portion of the 
DEVMODE data structure for the 
printer driver. © 


Returns the dmFields field of the | 
printer driver’s DEVMODE data 
structure. The dmFields bitfield indi- 
cates which fields in the 
device-independent portion of the 
structure are supported by the printer 
driver. 


Returns a POINT data structure con- 
taining the maximum paper size that 
the dmPaperLength and dmPaper- 
Width fields of the printer driver’s 
DEVMODE data structure can 
specify. 


Returns a POINT data structure con- 
taining the minimum paper size that 
the dmPaperLength and dmPaper- 
Width fields of the printer driver’s 
DEVMODE data structure can 
specify. 
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DeviceCapabilities 


Return Value 


Parameter 


Value 


DC_PAPERS 


DC_PAPERSIZE 


DC_SIZE 


DC_VERSION 


Type/Description 


Meaning 


Retrieves a list of supported paper 
sizes. The function copies the list to 
[pOutput as a WORD array and re- 
turns the number of entries in the 
array. If JpOutput is NULL, the func- 
tion returns the number of supported 
paper sizes to allow the application 
the opportunity to allocate a buffer 
with the correct size. See the descrip- 
tion of the dmPaperSize field of the 
DEVMODE data structure for infor- 
mation on these values. 


Copies the dimensions of supported 
paper sizes in tenths of a millimeter 
to an array of POINT structures in 
[pOutput. This allows an application 
to obtain information about nonstand- 
ard paper sizes. 


Returns the dmSize field of the 
printer driver’s DEVMODE data 
structure. 


Returns the specification version to 
which the printer driver conforms. 


[pOutput LPSTR Points to an array of bytes. The actual format of the 
array depends on the setting of n/ndex. If set to zero, DeviceCapa- 
bilities returns the number of bytes required for the output data. 


IpDevMode 


DEVMODE FAR * 


Points to a DEVMODE data structure. If 


lpDevMode is NULL, this function retrieves the current default in- 
itialization values for the specified printer driver. Otherwise, the 
function retrieves the values contained in the structure to which 


IpDevMode points. 


The return value depends on the setting of the nJndex parameter; see the description of that 


parameter for details. 
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Comments 


This function is supplied by the printer driver. An application must include the 
DRIVINIT.H file and call the LoadLibrary and GetProcAddress functions to call the 
DeviceCapabilities function. 


DeviceMode 


Syntax 


Return Value 


Comments 


void DeviceMode(hWnd, hModule, lpDeviceName, IpOutput) 


This function sets the current printing modes for the device identified by the JpDestDev- 
Type by prompting for those modes using a dialog box. An application calls the Device- 
Mode function to allow the user to change the printing modes of the corresponding device. 
The function copies the mode information to the environment block associated with the 
device and maintained by GDI. 


Parameter — Type/Description 
hWnd HWND Identifies the window that will own the dialog box. 
hModule HANDLE Identifies the printer-driver module. The applica- 


tion should retrieve this handle by calling either the 
GetModuleHandle or LoadLibrary function. 


IpDeviceName LPSTR Points to a null-terminated character string that speci- 
fies the name of the specific device to be supported (for 
example, Epson FX-80). The device name is the same as the 
name passed to the CreateDC function. 


IpOutput LPSTR Points to a null-terminated character string that speci- 
fies the DOS file or device name for the physical output medium 
(file or output port). The output name is the same as the name 
passed to the CreateDC function. 


None. 


The DeviceMode function is actually part of the printer’s device driver, and not part of 
GDI. To call this function, the application must load the printer device driver by calling 
LoadLibrary and retrieve the address of the function by using the GetProcAddress func- 
tion. The application can then use the address to set up the printer. 
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DialogBox 
Syntax 


Return Value 


Comments 


Callback Function 


int DialogBox(h/nstance, IpTemplateName, hWndParent, IpDialogFunc) 


This function creates a modal dialog box that has the size, style, and controls specified by 
the dialog-box template given by the /pTemplateName parameter. The hWndParent para- 
meter identifies the application window that owns the dialog box. The callback function 
pointed to by the IpDialogF unc parameter processes any messages received by the dialog 
box. 


The DialogBox function does not return control until the callback function terminates the 
modal dialog box by calling the EndDialog function. 


Parameter Type/Description 


hInstance HANDLE Identifies an instance of the module whose exe- 
‘cutable file contains the dialog-box template. 


[pTemplateName LPSTR Points to a character string that names the dialog-box 
template. The string must be a null-terminated character string. 

hWnaParent HWND Identifies the window that owns the dialog box. 

[pDialogFunc FARPROC Is the procedure-instance address of the dialog 


function. See the fcllowing “Comments” section for details. 


The return value specifies the value of the nResult parameter in the EndDialog function 
that is used to terminate the dialog box. Values returned by the application’s dialog box are 
processed by Windows and are not returned to the application. The return value is —1 if the 
function could not create the dialog box. 


The DialogBox function calls the GetDC function in order to obtain a display-context. 
Problems will result if all the display contexts in the Windows display-context cache have 
been retrieved by GetDC and DialogBox attempts to access another display context. 


A dialog box can contain up to 255 controls. 


The callback function must use the Pascal calling convention and must be declared FAR. 


int FAR PASCAL DialogFunc(hDlg, wMsg, wParam, lParam) 
HWND /Dig; 

WORD wMsg; 

WORD wParam; 

DWORD /Param; 


DialogBoxindirect 
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DialogFunc is a placeholder for the application-supplied function name. The actual name 
must be exported by including it in an EXPORTS statement in the application’s module- 
definition file. 


Parameter Description 

hDig Identifies the dialog box that receives the message. 

wMseg Specifies the message number. 

wParam Specifies 16 bits of additional message-dependent information. 
lParam Specifies 32 bits of additional message-dependent information. 


Return Value 


The callback function should return nonzero if the function processes the message and 
zero if it does not. 


Comments 


Although the callback function is similar to a window function, it must not call the Def- 
WindowProc function to process unwanted messages. Unwanted messages are processed 
internally by the dialog-class window function. 


The callback-function address, passed as the /pDialogF unc parameter, must be created by 
using the MakeProcInstance function. 


DialogBoxindirect 
' Syntax 


int DialogBoxIndirect(i/nstance, hDialogTemplate, hWndParent, lpDialogFunc) 


This function creates an application’s modal dialog box that has the size, style, and con- 
trols specified by the dialog-box template associated with the hDialogTemplate parameter. 
The hWndParent parameter identifies the application window that owns the dialog box. 
The callback function pointed to by IpDialogFunc processes any messages received by the 
dialog box. 


The DialogBoxIndirect function does not return control until the callback function termi- 
nates the modal dialog box by calling the EndDialog function. 


Parameter Type/Description 


hInstance HANDLE Identifies an instance of the module whose exe- 
cutable file contains the dialog-box template. 
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Return Value 


Comments 


Callback Function 


Parameter Type/Description 


hDialogTemplate HANDLE Identifies a block of global memory that contains a 
DLGTEMPLATE data structure. 


hWndParent HWND Identifies the window that owns the dialog box. 


lpDialogFunc FARPROC Is the procedure-instance address of the dialog 
function. See the following “Comments” section for details. 


The return value specifies the value of the wResult parameter specified in the EndDialog 
function that is used to terminate the dialog box. Values returned by the application’s 
dialog box are processed by Windows and are not returned to the application. The return 
value is —1 if the function could not create the dialog box. 


A dialog box can contain up to 255 controls. 


The callback function must use the Pascal calling convention and be declared FAR. 


BOOL FAR PASCAL DialogFunc(hDlg, wMsg, wParam, |Param) 
HWND /Dig; 

WORD wMszg; 

WORD wParam; 

DWORD /Param; 


DialogFunc is a placeholder for the application-supplied function name. The actual name 
must be exported by including it in an EXPORTS statement in the application’s module- 
definition file. 


Parameter Description 

hDlg Identifies the dialog box that receives the message. 

wMsg Specifies the message number. 

wParam Specifies 16 bits of additional message-dependent information. 
[Param Specifies 32 bits of additional message-dependent information. 


Return Value 


The callback function should return nonzero if the function processes the message and 
zero if it does not. 


Q 
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Comments 


Although the callback function is similar to a window function, it must not call the Def- 
WindowProc function to process unwanted messages. Unwanted messages are processed 
internally by the dialog-class window function. 


The callback-function address, passed as the /pDialogF unc parameter, must be created by 
using the MakeProcInstance function. 


DialogBoxindirectParam 


Syntax 


Return Value 


int DialogBoxIndirectParam(hlnstance, hDialogTemplate, hWndParent, 
[pDialogFunc, dwlnitParam) 


This function creates an application’s modal dialog box, sends a WM_INITDIALOG 
message to the dialog function before displaying the dialog box and passes dwInitParam 
as the message /Param. This message allows the dialog function to initialize the dialog- 
box controls. 


For more information on creating an application modal dialog box, see the description of 
the DialogBoxIndirect function. 


Parameter Type/Description 


hInstance HANDLE Identifies an instance of the module whose exe- 
cutable file contains the dialog-box template. 


hDialogTemplate HANDLE Identifies a block of global memory that contains a 
DLGTEMPLATE data structure. 


hWndParent HWND Identifies the window that owns the dialog box. 


IpDialogFunc FARPROC Is the procedure-instance address of the dialog 
function. For details, see the “Comments” section in the descrip- 
tion of the DialogBoxIndirect function. 


dwlnitParam DWORD Isa 32-bit value which DialogBoxIndirectParam 
passes to the dialog function when it creates the dialog box. 


The return value specifies the value of the wResult parameter specified in the EndDialog 
function that is used to terminate the dialog box. Values returned by the application’s 
dialog box are processed by Windows and are not returned to the application. The return 
value is —1 if the function could not create the dialog box. 
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DialogBoxParam 


Syntax 


Return Value 


int DialogBoxParam(h/nstance, lpTemplateName, hWndParent, IpDialogFunc, 
dwInitParam) 


This function creates a modal dialog box, sends a WM_INITDIALOG message to the 
dialog function before displaying the dialog box, and passes dw/nitParam as the message 
lParam. This message allows the dialog function to initialize the dialog-box controls. 


For more information on creating a modal dialog box, see the description of the Dialog- 
Box function. 


Parameter Type/Description 


hInstance HANDLE Identifies an instance of the module whose exe- 
cutable file contains the dialog-box template. 


IpTemplateName LPSTR Points to a character string that names the dialog-box 
template. The string must be a null-terminated character string. 

hWndParent HWND Identifies the window that owns the dialog box. 

IpDialogFunc FARPROC Is the procedure-instance address of the dialog 


function. For details, see the “Comments” section of the descrip- 
tion of the DialogBox function. 


dwlnitParam DWORD Is a 32-bit value which DialogBoxParam passes to 
the dialog function when it creates the dialog box. 


The return value specifies the value of the nResult parameter in the EndDialog function 
that is used to terminate the dialog box. Values returned by the application’s dialog box are 
processed by Windows and are not returned to the application. The return value is —1 if the 
function could not create the dialog box. 


DispatchMessage 


Syntax 


LONG _DispatchMessage(/pMsg) 


This function passes the message in the MSG structure pointed to by the /pMsg parameter 
to the window function of the specified window. 
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Parameter Type/Description 


IpMsg LPMSG Points to an MSG data structure that contains 
message information from the Windows application queue. 


The structure must contain valid message values. If JpMsg points 
to a WM_TIMER message and the /Param parameter of the 
WM_TIMER message is not NULL, then the /Param parameter 
is the address of a function that is called instead of the window 
function. 


Return Value The return value specifies the value returned by the window function. Its meaning depends 
on the message being dispatched, but generally the return value is ignored. 


DigDirList 
Syntax int DigDirList(hD/g, [pPathSpec, nIDListBox, nIDStaticPath, wFiletype) 


This function fills a list-box control with a file or directory listing. It fills the list box 
specified by the n/DListBox parameter with the names of all files matching the pathname 
given by the /pPathSpec parameter. 


The DlgDirList function shows subdirectories enclosed in square brackets ([ ]), and shows 
drives in the form [—x—], where x is the drive letter. 


The /pPathSpec parameter has the following form: 
[drive:]] [[ [\]directory[\directory]...\]] [filename] 


In this example, drive is a drive letter, directory is a valid directory name, and filename is a 
valid filename that must contain at least one wildcard character. The wildcard characters 
are a question mark (?), meaning “match any character,” and an asterisk (*), meaning 
“match any number of characters.” 


If the JpPathSpec parameter includes a drive and/or directory name, the current drive and 
directory are changed to the designated drive and directory before the list box is filled. The 
text control identified by the n/DStaticPath parameter is also updated with the new drive 
and/or directory name. 


After the list box is filled, /pPathSpec is updated by removing the drive and/or directory 
portion of the pathname. 


DigDirList sends LB_RESETCONTENT and LB_DIR messages to the list box. 
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Parameter Type/Description 
hDlg HWND Identifies the dialog box that contains the list box. 
IpPathSpec LPSTR Points to a pathname string. The string must be a null- 


terminated character string. 


nIDListBox int Specifies the identifier of a list-box control. If n/DListBox 
is zero, DigDirList assumes that no list box exists and does not 
attempt to fill it. 


nlDStaticPath int Specifies the identifier of the static-text control used for 
displaying the current drive and directory. If nJDStaticPath is 
zero, DigDirList assumes that no such text control is present. 


wFiletype WORD _ Specifies DOS file attributes of the files to be dis- 
played. It can be any combination of the values given in Table 
4.6, “DOS File Attributes.” Values can be combined by using the 
bitwise OR operator. 


Return Value The return value specifies the outcome of the function. It is nonzero if a listing was made, 
even an empty listing. A zero return value implies that the input string did not contain a 
valid search path. 


The wFiletype parameter specifies the DOS attributes of the files to be listed. Table 4.6 de- 
scribes these attributes. 


Table 4.6 DOS File Attributes 


Attribute Value Meaning 


0x0000 Read/write data files with no additional attributes 
0x0001 Read-only files 

0x0002 Hidden files 

0x0004 System files 

0x0010 Subdirectories 

0x0020 Archives 

0x2000 LB_DIR flag! 

0x4000 Drives 

0x8000 Exclusive bit” 


‘if the LB_DIR flag is set, Windows places the messages generated by DlgDirList in the application’s queue; 
otherwise they are sent directly to the dialog function. 


If the exclusive bit is set, only files of the specified type are listed. Otherwise, files of the specified type are 
listed in addition to normal files. 
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DigDirListComboBox 


Syntax 


int DlgDirListComboBox(hDie, IpPathSpec, nIDComboBox, nIDStaticP ath, wFiletype) 


This function fills the list box of a combo-box control with a file or directory listing. It fills 
the list box of the combo box specified by the n/DComboBox parameter with the names of 
all files matching the pathname given by the /pPathSpec parameter. 


The DigDirListComboBox function shows subdirectories enclosed in square brackets 
([ ]), and shows drives in the form [—x—], where x is the drive letter. 


The /pPathSpec parameter has the following form: 
[drive:]] [[ [\Jdirectory[\directory]...\]] [filename] 


In this example, drive is a drive letter, directory is a valid directory name, and filename is a 
valid filename that must contain at least one wildcard character. The wildcard characters 
are a question mark (?), meaning “match any character,” and an asterisk (*), meaning 
“match any number of characters.” 


If the /pPathSpec parameter includes a drive and/or directory name, the current drive and 
directory are changed to the designated drive and directory before the list box is filled. The 
text control identified by the nJDStaticPath parameter is also updated with the new drive 
and/or directory name. 


After the combo-box list box is filled, JpPathSpec is updated by removing the drive and/or 
directory portion of the pathname. 


DigDirListComboBox sends CB_RESETCONTENT and CB_DIR messages to the 
combo box. 


Parameter Type/Description 
hDlg HWND Identifies the dialog box that contains the combo box. 
IpPathSpec LPSTR Points to a pathname string. The string must be a null- 


terminated character string. 


nIDComboBox int Specifies the identifier of a combo-box control in a dialog 
box. If nJ[DComboBox is zero, DigDirListComboBox assumes 
that no combo box exists and does not attempt to fill it. 


nIDStaticPath int Specifies the identifier of the static-text control used for 
displaying the current drive and directory. If nJDStaticPath is 
zero, DigDirListComboBox assumes that no such text control 
is present. 
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Return Value 


DigDirSelect 
Syntax 


Return Value 


Comments 


Parameter Type/Description 


wFiletype WORD Specifies DOS file attributes of the files to be dis- 
played. It can be any combination of the values given in Table 
4.6, “DOS File Attributes.” Refer to the description of the 
DigDirList function for this table. Values can be combined by 
using the bitwise OR operator. 


The return value specifies the outcome of the function. It is nonzero if a listing was made, 
even an empty listing. A zero return value implies that the input string did not contain a 
valid search path. 


BOOL DlgDirSelect(;Dig, IpString, nIDListBox) 


This function retrieves the current selection from a list box. It assumes that the list box has 
been filled by the DilgDirList function and that the selection is a drive letter, a file, or a 
directory name. 


The DigDirSelect function copies the selection to the buffer given by the /pString para- 
meter. If the current selection is a directory name or drive letter, DigDirSelect removes the 
enclosing square brackets (and hyphens, for drive letters) so that the name or letter is ready 
to be inserted into a new pathname. If there is no selection, /pString does not change. 


DigDirSelect sends LB_GETCURSEL and LB_GETTEXT messages to the list box. 


Parameter Type/Description 
hDlg HWND Identifies the dialog box that contains the list box. 
IpString LPSTR Points to a buffer that is to receive the selected 
pathname. 
nIDListBox ee Specifies the integer ID of a list-box control in the dialog 
OX. 


The return value specifies the status of the current list-box selection. It is nonzero if the 


current selection is a directory name. Otherwise, it is zero. 


The DigDirSelect function does not allow more than one filename to be returned from a 
list box. 
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The list box must not be a multiple-selection list box. If it is, this function will not return a 
zero value and /pString will remain unchanged. 


DigDirSelectComboBox 
Syntax BOOL DlgDirSelectComboBox(hDlg, lpString, nIDComboBox) 


This function retrieves the current selection from the list box of a combo box. It assumes 
that the list box has been filled by the DlgDirListComboBox function and that the selec- 
tion is a drive letter, a file, or a directory name. 


The DigDirSelectComboBox function copies the selection to the buffer given by the 
IpString parameter. If the current selection is a directory name or drive letter, DigDir- 
SelectComboBox removes the enclosing square brackets (and hyphens, for drive letters) 
so that the name or letter is ready to be inserted into a new pathname. If there is no selec- 
tion, /pString does not change. 


DigDirSelectComboBox sends CB_GETCURSEL and CB_GETLBTEXT messages to 
the combo box. 


Parameter Type/Description 
hDig HWND Identifies the dialog box that contains the combo box. 
IpString LPSTR Points to a buffer that is to receive the selected 
pathname. 
nIDComboBox int Specifies the integer ID of the combo-box control in the 
dialog box. 
Return Value The return value specifies the status of the current combo-box selection. It is nonzero if the 


current selection is a directory name. Otherwise, it is zero. 


Comments The DigDirSelectComboBox function does not allow more than one filename to be re- 
turned from a combo box. 


DOS3Call 


This function allows an application to issue a DOS function-request interrupt 21H. An 
application can use this function instead of a directly coded DOS 21H interrupt. The 
DOS3Call function executes somewhat faster than the equivalent DOS 21H software inter- 
rupt under Windows. 
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DPtoLP 


DPtoLP 
Syntax 


Return Value 


An application can call this function only from an assembly-language routine. It is ex- 
ported from KERNEL.EXE and is not defined in any Windows include files. 


To use this function call, an application should declare it in an assembly-language program 


_ as shown: 


extrn DOS3Call :far 


If the application includes CMACROS.INC, the application declares it as shown: 
extrnFP Dos3Cal} 


Before calling DOS3Call, all registers must be set as for an actual INT 21H. All registers 
at the function’s exit are the same as for the corresponding INT 21H function. 


This function has no parameters and returns the registers of the DOS function. 
The following is an example of using DOS3Call: 
extrn DOS3Call : far 


; set registers 
mov ah, DOSFUNC 
cCall DOS3Call 


BOOL DPtoLP(hDC, IpPoints, nCount) 


This function converts device points into logical points. The function maps the coordinates 
of each point specified by the /pPoints parameter from the device coordinate system into 
GDI’s logical coordinate system. The conversion depends on the current mapping mode 
and the settings of the origins and extents for the device’s window and viewport. 


Parameter Type/Description 

hDC HDC Identifies the device context. 

[pPoints LPPOINT Points to an array of points. Each point must be a 
POINT data structure. 

nCount int Specifies the number of points in the array. 


The return value specifies whether the conversion has taken place. It is nonzero if all 
points are converted. Otherwise, it is zero. 
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DrawFocusRect 


Syntax 


Return Value 


Comments 


Drawlicon 
Syntax 


void DrawFocusRect(hDC, [pRect) 


This function draws a rectangle in the style used to indicate focus. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpRect LPRECT Points to a RECT data structure that specifies the 


coordinates of the rectangle to be drawn. 


None. 


Since this is an XOR function, calling this function a second time with the same rectangle 
removes the rectangle from the display. 


The rectangle drawn by this function cannot be scrolled. To scroll an area containing a 
rectangle drawn by this function, call DrawFocusRect to remove the rectangle from the 
display, scroll the area, and then call DrawFocusRect to draw the rectangle in the new 
position. 


BOOL DrawlIcon(hADC, X, Y, hIcon) 


This function draws an icon on the specified device. The DrawIcon function places the 
icon’s upper-left corner at the location specified by the X and Y parameters. The location is 
subject to the current mapping mode of the device context. 


Parameter Type/Description 

hDC HDC Identifies the device context for a window. 

Xx int Specifies the logical x-coordinate of the upper-left corner of the 
icon. 

Y . int Specifies the logical y-coordinate of the upper-left corner of the 
icon. 


hIcon HICON Identifies the icon to be drawn. 
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DrawMenuBar 


Return Value 


Comments 


DrawMenuBar 
Syntax 


Return Value 


DrawText 
Syntax 


The return value specifies the outcome of the function. It is nonzero if the function is 
successful. Otherwise, it is zero. 


The icon resource must have been previously loaded by using the LoadIcon function. The 
MM_TEXT mapping mode must be selected prior to using this function. 


void DrawMenuBar(hWnd) 


This function redraws the menu bar. If a menu bar is changed after Windows has created 
the window, this function should be called to draw the changed menu bar. 


Parameter  Type/Description 
hWnd HWND Identifies the window whose menu needs redrawing. 
None. 


int DrawText(hDC, IpString, nCount, lpRect, wFormat) 


This function draws formatted text in the rectangle specified by the /pRect parameter. It for- 
mats text by expanding tabs into appropriate spaces, justifying text to the left, right, or 
center of the given rectangle, and breaking text into lines that fit within the given 

rectangle. The type of formatting is specified by the wFormat parameter. 


The DrawText function uses the device context’s selected font, text color, and background 
color to draw the text. Unless the DT_NOCLIP format is used, DrawText clips the text so 
that the text does not appear outside the given rectangle. All formatting is assumed to have 
multiple lines unless the DT_SINGLELINE format is given. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpString LPSTR Points to the string to be drawn. If the nCount parameter 


is —1, the string must be null-terminated. 


nCount int Specifies the number of bytes in the string. If nCount is -1, 
then /pString is assumed to be a long pointer to a null-terminated 
string and DrawText computes the character count automatically. 
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Parameter Type/Description 


IpRect LPRECT Points toa RECT data structure that contains the 
rectangle (in logical coordinates) in which the text is to be formatted. 


wFormat WORD _ Specifies the method of formatting the text. It can be a 
combination of the values given in Table 4.7, “DrawText Formats.” 


Return Value . The return value specifies the height of the text. 


Comments If the selected font is too large for the specified rectangle, the DrawText function does not 
attempt to substitute a smaller font. 


Table 4.7 lists the values for the wFormat parameter. These values can be combined by 
using the bitwise OR operator. Note that the DT_CALCRECT, DT_EXTERNALLEAD- 
ING, DT_INTERNAL, DT_NOCLIP, and DT_NOPREFIX values cannot be used with the 
DT_TABSTOP value. 


Table 4.7 DrawText Formats 


Value Meaning 

DT_BOTTOM Specifies bottom-justified text. This value must be combined 
with DT_SINGLELINE. 

DT_CALCRECT Determines the width and height of the rectangle. If there are 


multiple lines of text, DrawText will use the width of the 
rectangle pointed to by the /pRect parameter and extend the 
base of the rectangle to bound the last line of text. If there is 
only one line of text, DrawText will modify the right side of 
the rectangle so that it bounds the last character in the line. In 
either case, DrawText retums the height of the formatted text 
but does not draw the text. 


DT_CENTER Centers text horizontally. 
DT_EXPANDTABS Expands tab characters. The default number of characters per 
tab is eight. 


DT_EXTERNALLEADING Includes the font external leading in line height. Normally, ex- 
ternal leading is not included in the height of a line of text. 


DT_LEFT Aligns text flush-left. 


DT_NOCLIP Draws without clipping. DrawText is somewhat faster when 
DT_NOCLIP is used. 
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Table 4.7 DrawText Formats (continued) 


Value 


DT_NOPREFIX 


DT_RIGHT 
DT_SINGLELINE 


DT_TABSTOP 


DT_TOP 


DT_VCENTER 
DT_WORDBREAK 


Meaning 


Tums off processing of prefix characters. Normally, DrawText 
interprets the mnemonic-prefix character “&” as a directive to 
underscore the character that follows, and the mnemonic-prefix 
characters “&&” as a directive to print a single “&”. By speci- 
fying DT_NOPREFIX, this processing is turned off. 


Aligns text flush-right. 


- Specifies single line only. Carriage returns and linefeeds do not 


break the line. 


Sets tab stops. The high-order byte of the wFormat parameter 
is the number of characters for each tab. The default number of 
characters per tab is eight. 


Specifies top-justified text (single line only). 
Specifies vertically centered text (single line only). 


Specifies word breaking. Lines are automatically broken be- 
tween words if a word would extend past the edge of the 
rectangle specified by the /pRect parameter. A carriage re- 
turn/line sequence will also break the line. 


Ellipse 
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Ellipse 
Syntax 


Return Value 


Comments 


BOOL Ellipse(iDC, XJ, Y1, X2, Y2) 


This function draws an ellipse. The center of the ellipse is the center of the bounding 
rectangle specified by the X/, YJ, X2, and Y2 parameters. The ellipse border is drawn with 
the current pen, and the interior is filled with the current brush. 


If the bounding rectangle is empty, nothing is drawn. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
Xl int Specifies the logical x-coordinate of the upper-left corner of the 


bounding rectangle. 


Y/ int Specifies the logical y-coordinate of the upper-left corner of the 
bounding rectangle. 


X2 int Specifies the logical x-coordinate of the lower-right corner of 
the bounding rectangle. 


Y2 int Specifies the logical y-coordinate of the lower-right corner of 
the bounding rectangle. 


The return value specifies whether the ellipse is drawn. It is nonzero if the ellipse is drawn. 
Otherwise, it is zero. 


The width of the rectangle, specified by the absolute value of X2 — X/, must not exceed 
32,767 units. This limit applies to the height'of the rectangle as well. 


The current position is neither used nor updated by this function. 


EmptyClipboard 


Syntax 


BOOL EmptyClipboard() 


This function empties the clipboard and frees handles to data in the clipboard. It then as- 
signs ownership of the clipboard to the window that currently has the clipboard open. 


This function has no parameters. 
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Return Value The return value specifies the status of the clipboard. It is nonzero if the clipboard is 
emptied. It is zero if an error occurs. 


Comments The clipboard must be open when the EmptyClipboard function is called. 
EnableHardwarelnput 
Syntax BOOL = EnableHardwareInput(bEnablelnput) 


This function disables mouse and keyboard input. The input is saved if the bEnableInput 
parameter is TRUE and discarded if it is FALSE. 


Parameter Type/Description 


bEnableInput BOOL _ Specifies that the function should save input if the 
bEnableInput parameter is set to a nonzero value; specifies that 
the function should discard input if the bEnableInput parameter 
is set to zero. 


Return Value The return value specifies whether mouse and keyboard input is disabled. It is nonzero if 
input was previously enabled. Otherwise, it is zero. The default return value is nonzero 
(TRUE). 

EnableMenultem 

Syntax BOOL  EnableMenultem(;Menu, wi/DEnableltem, wEnable) 


This function enables, disables, or grays a menu item. 


Parameter Type/Description 
hMenu HMENU | Specifies the menu. 


wlDEnableltem WORD Specifies the menu item to be checked. The w/DEna- 
bleltem parameter can specify pop-up menu items as well as menu 
items. 


wEnable WORD Specifies the action to take. It can be a combination of 
MF_DISABLED, MF_ENABLED, or MF_GRAYED, with 
MF_BYCOMMAND or MF_BYPOSITION. These values can be 
combined by using the bitwise OR operator. These values have 
the following meanings: 
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Parameter Type/Description 

Value Meaning 

MF_BYCOMMAND Specifies that the w/DEnableltem 
parameter gives the menu item ID 
(MF_BYCOMMAND is the default 
ID). 

MF_BYPOSITION Specifies that the w/DEnableltem par- 
ameter gives the position of the menu 
item (the first item is at position 
zero). 

MF_DISABLED Menu item is disabled. 

MF_ENABLED Menu item is enabled. 

MF_GRAYED Menu item is grayed. 

Return Value The return value specifies the previous state of the menu item. The return value is —1 if the 
menu item does not exist. 
Comments To disable or enable input to a menu bar, see the WM_SYSCOMMAND message. 


EnableWindow 
Syntax BOOL  EnableWindow(hWnd, bEnable) 


This function enables or disables mouse and keyboard input to the specified window or 
control. When input is disabled, input such as mouse clicks and key presses are ignored by 
the window. When input is enabled, all input is processed. 


The Enable Window function enables mouse and keyboard input to a window if the 
bEnable parameter is nonzero, and disables it if bEnable is zero. 


Parameter Type/Description 
hWnd HWND Identifies the window to be enabled or disabled. 
bEnable BOOL _ Specifies whether the given window is to be enabled or dis- 


abled. 
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EndDeferWindowPos 


Return Value 


Comments 


The return value specifies the outcome of the function. It is nonzero if the window is 
enabled or disabled as specified. It is zero if an error occurs. 


A window must be enabled before it can be activated. For example, if an application is dis- 
playing a modeless dialog box and has disabled its main window, the main window must 
be enabled before the dialog box is destroyed. Otherwise, another window will get the 
input focus and be activated. If a child window is disabled, it is ignored when Windows 
tries to determine which window should get mouse messages. 


Initially, all windows are enabled by default. EnableWindow must be used to disable a 
window explicitly. 


EndDeferWindowPos 


Syntax 


Return Value 


void EndDeferWindowPos(hWinPosInfo) 


This function simultaneously updates the position and size of one or more windows ina 
single screen-refresh cycle. The hWinPosInfo parameter identifies a multiple window-posi- 
tion data structure that contains the update information for the windows. The Defer- 
WindowPos function stores the update information in the data structure; the BeginDefer- 
WindowPos function creates the initial data structure used by these functions. 


Parameter Type/Description 


hWinPosInfo HANDLE Identifies a multiple window-position data struc- 
ture that contains size and position information for one or more 
windows. This structure is returned by the BeginDeferWindow- 
Pos function or the most recent call to the Defer WindowPos 
function. 


None. 


EndDialog 


Syntax 


void EndDialog(Dig, nResult) 


This function terminates a modal dialog box and returns the given result to the DialogBox 
function that created the dialog box. The EndDialog function is required to complete pro- 
cessing whenever the DialogBox function is used to create a modal dialog box. The func- 
tion must be used in the dialog function of the modal dialog box and should not be used for 
any other purpose. 
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The dialog function can call EndDialog at any time, even during the processing of the 
WM_INITDIALOG message. If called during the WM_INITDIALOG message, the dialog 
box is terminated before it is shown or before the input focus is set. 


EndDialog does not terminate the dialog box immediately. Instead, it sets a flag that 
directs the dialog box to terminate as soon as the dialog function ends. The EndDialog 
function retums to the dialog function, so the dialog function must return control to 


Windows. 
Parameter Type/Description 
hDig HWND Identifies the dialog box to be destroyed. 
nResult int Specifies the value to be returned from the dialog box to the 
DialogBox function that created it. 
Return Value None. 
EndPaint 
Syntax void EndPaint(hWnd, lpPaint) 
This function marks the end of painting in the given window. The EndPaint function is re- 
quired for each call to the BeginPaint function, but only after painting is complete. 
Parameter Type/Description 
hWnd ~ HWND Identifies the window that is repainted. 
lpPaint LPPAINTSTRUCT Points to a PAINTSTRUCT data structure 
that contains the painting information retrieved by the BeginPaint 
function. 
Return Value None. 
Comments If the caret was hidden by the BeginPaint function, EndPaint restores the caret to the 


screen. 
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EnumChildWindows 


EnumChildWindows 


Syntax 


Return Value 


Comments 


Callback Function 


BOOL = EnumChildWindows(hWndParent, lpEnumFunc, |[Param) 


This function enumerates the child windows that belong to the specified parent window by 
passing the handle of each child window, in turn, to the application-supplied callback func- 
tion pointed to by the /pEnumFunc parameter. 


The EnumChild Windows function continues to enumerate windows until the called func- 
tion returns zero or until the last child window has been enumerated. 


Parameter Type/Description 

hWndParent HWND Identifies the parent window whose child windows 
are to be enumerated. 

lpEnumF unc FARPROC Is the procedure-instance address of the callback 
function. 

[Param DWORD Specifies the value to be passed to the callback 


function for the application’s use. 


The return value specifies nonzero if all child windows have been enumerated. Otherwise, 
it is zero. 


This function does not enumerate pop-up windows that belong to the hWndParent parame- 
ter. 


The address passed as the JpEnumFunc parameter must be created by using the Make- 
ProcInstance function. 


The callback function must use the Pascal calling convention and must be declared FAR. 


BOOL FAR PASCAL EnumFunc(hWnd, lParam) 
HWND hWnd; 
DWORD /Param; 


EnumF unc is a placeholder for the application-supplied function name. The actual name 
must be exported by including it in an EXPORTS statement in the application’s module- 
definition file. 
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Parameter Description 

hWnd Identifies the window handle. 

[Param Specifies the long parameter argument of the EnumChild Windows 
function. 


Return Value 


The callback function should return a nonzero value to continue enumeration; it should re- 
turn zero to stop enumeration. 


EnumClipboardFormats 


Syntax 


Return Value 


Comments 


WORD = EnumClipboardFormats(wFormat) 


This function enumerates the formats found in a list of available formats that belong to the 
clipboard. On each call to this function, the wFormat parameter specifies a known availa- 
ble format, and the function returns the format that appears next in the list. The first format 
in the list can be retrieved by setting wFormat to zero. 


Parameter Type/Description 


wFormat WORD Specifies a known format. 


The return value specifies the next known clipboard data format. It is zero if wFormat 
specifies the last format in the list of available formats. It is zero if the clipboard is not 
open. 


Before it enumerates the formats by using the EnumClipboardFormats function, an appli- 
cation must open the clipboard by using the OpenClipboard function. 


The order that an application uses for putting alternative formats for the same data into the 
clipboard is the same order that the enumerator uses when returning them to the pasting 
application. The pasting application should use the first format enumerated that it can 
handle. This gives the donor a chance to recommend formats that involve the least loss of 
data. 
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EnumFonts 


EnumFonts 
Syntax 


Return Value 


Comments 


Callback Function 


int EnumFonts(iDC, IpFacename, lpFontFunc, lpData) 


This function enumerates the fonts available on a given device. For each font having the 
typeface name specified by the /pFacename parameter, the EnumFonts function retrieves 
information about that font and passes it to the function pointed to by the /pFontFunc para- 
meter. The application-supplied callback function can process the font information as 
desired. Enumeration continues until there are no more fonts or the callback function re- 
turns zero. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpFacename LPSTR Points to a null-terminated character string that specifies 


the typeface name of the desired fonts. If Jp>Facename is NULL, 
EnumFonts randomly selects and enumerates one font of each avail- 
able typeface. 


IpFontFunc FARPROC Is the procedure-instance address of the callback func- 
tion. See the following “Comments” section for details. 


IpData LPSTR Points to the application-supplied data. The data is passed 
to the callback function along with the font information. 


The return value specifies the last value returned by the callback function. Its meaning is 
user-defined. 


The address passed as the [pFontFunc parameter must be created by using the Make- 
ProcInstance function. 


The callback function must use the Pascal calling convention and must be declared FAR. 


int FAR PASCAL FontFunc(lpLogFont, IpTextMetrics, nF ontType, lpData) 
LPLOGFONT /pLogFont; 

LPTEXTMETRICS IpTextMetrics; 

short nFontType; 

LPSTR /pData; 


FontFunc is a placeholder for the application-supplied function name. The actual name 
must be exported by including it in an EXPORTS statement in the application’s module- 
definition file. 
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EnumMetaFile 
Syntax 


Parameter Description . 

lpLogFont Points to a LOGFONT data structure that contains information 
about the logical attributes of the font. 

lpTextMetrics Points to a TEXTMETRIC data structure that contains informa- 
tion about the physical attributes of the font. 

nFontType - Specifies the type of the font. 

lpData Points to the application-supplied data passed by EnumFonts. 


Return Value 


The return value can be any integer. 


Comments 


The AND (&) operator can be used with the RASTER_FONTTYPE and DEVICE_FONT- 
TYPE constants to determine the font type. The RASTER_FONTTYPE bit of the Font- 
Type parameter specifies whether the font is a raster or vector font. If the bit is one, the 
font is a raster font; if zero, it is a vector font. The DEVICE_FONTTYPE bit of FontType 
specifies whether the font is a device- or GDI-based font. If the bit is one, the font is a 
device-based font; if zero, it is a GDI-based font. 


If the device is capable of text transformations (scaling, italicizing, and so on) only the 
base font will be enumerated. The user must inquire into the device’s text-transformation 
abilities to determine which additional fonts are available directly from the device. GDI 
can simulate the bold, italic, underlined, and strikeout attributes for any GDI-based font. 


EnumFonts only enumerates fonts from the GDI internal table. This does not include 
fonts that are generated by a device, such as fonts that are transformations of fonts from 
the internal table. The GetDeviceCaps function can be used to determine which transfor- 
mations a device can perform. This information is available by using the TEXTCAPS 
index. 


GDI can scale GDI-based raster fonts by one to five horizontally and one to eight verti- 
cally, unless PROOF_QUALITY is being used. 


BOOL EnumMetaFile(hDC, hMF, lpCallbackF unc, lpClientData) 


This function enumerates the GDI calls within the metafile identified by the AMF parame- 
ter. The EnumMetaFile function retrieves each GDI call within the metafile and passes it 
to the function pointed to by the /pCallbackFunc parameter. This callback function, an 
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Return Value 


Commenis 


Callback Function 


EnumMetaFile 


application-supplied function, can process each GDI call as desired. Enumeration con- 
tinues until there are no more GDI calls or the callback function returns zero. 


Parameter Type/Description 

hDC HDC Identifies the device context associated with the meta- 
file. 

hMF LOCALHANDLE Identifies the metafile. 

IpCallbackFunc FARPROC Is the procedure-instance callback function. See 


the following “Comments” section for details. 


IpClientData BYTE FAR * Points to the callback-function data. 


The return value specifies the outcome of the function. It is nonzero if the callback func- 
tion enumerates all the GDI calls in a metafile; otherwise, it returns zero. 


The callback function must use the Pascal calling convention and must be declared FAR. 


int FAR PASCAL EnumFunc(hDC, IpHTable, lpMFR, nOby, IpClientData) 

HDC hDC; 

LPHANDLETABLE IpHTable; 

LPMETARECORD IpMFR; 

int nObj; 

BYTE FAR * /pClientData; 

EnumF unc is a placeholder for the application-supplied function name. The actual name 


must be exported by including it in an EXPORTS statement in the application’s module- 
definition file. 


Parameter Description 

hDC Identifies the special device context that contains the metafile. 

lpHTable Points to a table of handles associated with the objects (pens, 
brushes, and so on) in the metafile. 

IpDMFR Points to a metafile record contained in the metafile. 

nObj Specifies the number of objects with associated handles in the 
handle table. 


IpClientData Points to the application-supplied data. 


Saueds 
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Return Value 


The function can carry out any desired task. It must return a nonzero value to continue 
enumeration, or a zero value to stop it. 


EnumObjects 
Syntax int EnumObjects(iDC, nObjectType, lpObjectFunc, lpData) 


This function enumerates the pens and brushes available on a device. For each object that 
belongs to the given style, the callback function is called with the information for that ob- 
ject. The callback function is called until there are no more objects or the callback function 


returns zero. 

Parameter Type/Description 

hDC HDC Identifies the device context. 

nObjectType int Specifies the object type. It can be one of the following 
values: 

OBJ_BRUSH 
OBJ_PEN 

IpObjectF unc FARPROC Is the procedure-instance address of the applica- 
tion-supplied callback function. See the following “Comments” 
section for details. 

IpData LPSTR Points to the application-supplied data. The data is 
passed to the callback function along with the object informa- 
tion. 

Return Value The return value specifies the last value returned by the callback function. Its meaning is 
user-defined. 
Comments The address passed as the IpObjectFunc parameter must be created by using the Make- 


ProcInstance function. 
The callback function must use the Pascal calling convention and must be declared FAR. 
Callback Function int FAR PASCAL ObjectFunc(IpLogObject, lpData) 


char FAR * [pLogObject; 
char FAR * [pData; 
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ObjectFunc is a placeholder for the application-supplied function name. The actual name 


must be exported by including it in an EXPORTS statement in the application’s module- 
definition file. 


Parameter Description 


lpLogObject Points to a LOGPEN or LOGBRUSH data structure that contains 
information about the logical attributes of the object. 


IpData Points to the application-supplied data passed to the EnumObjects 
function. 
EnumProps 
Syntax int EnumProps(hWnd, IpEnumFunc) 
This function enumerates all entries in the property list of the specified window. It enumer- 
ates the entries by passing them, one by one, to the callback function specified by IpEnum- 
Func. EnumProps continues until the last entry is enumerated or the callback function 
returns zero. 
Parameter Type/Description 
hWnd HWND Identifies the window whose property list is to be 
enumerated. 
[pEnumFunc FARPROC Is the procedure-instance address of the callback func- 
tion. See the following “Comments” section for details. 
Return Value The return value specifies the last value returned by the callback function. It is —1 if the 
function did not find a property for enumeration. 
Comments An application can remove only those properties which it has added. It should not remove 


properties added by other applications or by Windows itself. 


The following restrictions apply to the callback function: 


1. The callback function must not yield control or do anything that might yield control to 
other tasks. 


2. The callback function can call the RemoveProp function. However, the RemoveProp 


function can remove only the property passed to the callback function through the call- 
back function’s parameters. 


3. Acallback function should not attempt to add properties. 
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Fixed Data 
Segments 


Moveable Data 
Segments 


The address passed in the /pEnumFunc parameter must be created by using the Make- 
ProcInstance function. 


The callback function must use the Pascal calling convention and must be declared FAR. 
In applications and dynamic libraries with fixed data segments and in dynamic libraries 
with moveable data segments that do not contain a stack, the callback function must have 
the form shown below. 


Callback Function 


int FAR PASCAL EnumFunc(hWnd, IpString, hData) 
HWND hWnd; 

LPSTR I[pString; 

HANDLE hData; 


EnumF unc is a placeholder for the application-supplied function name. The actual name 
must be exported by including it in an EXPORTS statement in the application’s module- 
definition file. 


Parameter Description 
hWnd Identifies a handle to the window that contains the property list. 
IpString Points to the null-terminated character string associated with the data 


handle when the application called the SetProp function to set the 
property. If the application passed an atom instead of a string to the 
SetProp function, the /pString parameter contains the atom in its low- 
order word, and the high-order word is zero. 


hData Identifies the data handle. 


Return Value 


The callback function can carry out any desired task. It must return a nonzero value to con- 
tinue enumeration, or a zero value to stop it. 


The callback function must use the Pascal calling convention and must be declared FAR. 
In applications with moveable data segments and in dynamic libraries whose moveable 
data segments also contain a stack, the callback function must have the form shown below. 
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EnumTaskWindows 


Callback Function 


int FAR PASCAL EnumFunc(hWnd, nDummy, pString, hData) 
HWND hWnd; 

WORD nDummy; 

PSTR pString; 

HANDLE /hData; 


EnumFunc is a placeholder for the application-supplied function name. The actual name 
must be exported by including it in an EXPORTS statement in the application’s module- 
definition file. 


Parameter Description 

hWnd Identifies a handle to the window that contains the property list. 
nDummy Specifies a dummy parameter. 

pString Points to the null-terminated character string associated with the data 


handle when the application called the SetProp function to set the 
property. If the application passed an atom instead of a string to the 
SetProp function, the pString parameter contains the atom. 


hData Identifies the data handle. 


Return Value 


The callback function can carry out any desired task. It should return a nonzero value to 
continue enumeration, or a zero value to stop it. 


Comments 


The alternate form above is required since movement of the data will invalidate any long 
pointer to a variable on the stack, such as the /pString parameter. The data segment typi- 
cally moves if the callback function allocates more space in the local heap than is currently 
available. 


EnumTaskWindows 


Syntax 


BOOL = EnumTaskWindows(hTask, lpEnumFunc, lParam) 


This function enumerates all windows associated with the hTask parameter, which is re- 
turned by the GetCurrentTask function. (A task is any program that executes as an inde- 
pendent unit. All applications are executed as tasks and each instance of an application is a 
task.) The enumeration terminates when the callback function, pointed to by pEnumFunc, 
returns FALSE. 
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Parameter Type/Description 

hTask HANDLE Identifies the specified task. The GetCurrentTask 
function returns this handle. 

lpEnumF unc FARPROC Is the procedure-instance address of the window’s 
callback function. 

lParam DWORD _ Specifies the 32-bit value that contains additional 
parameters that are sent to the callback function pointed to by 


Return Value 


Comments 


Callback Function 


IpEnumF unc. 


The return value specifies the outcome of the function. It is nonzero if all the windows as- 
sociated with a particular task are enumerated. Otherwise, it is zero. 


The callback function must use the Pascal calling convention and must be declared FAR. 
The callback function must have the following form: 


BOOL FAR PASCAL EnumFunc(hWnd, lParam) 
HWND hWnd; 
DWORD /Param; . 


EnumFunc is a placeholder for the application-supplied function name. The actual name | 
must be exported by including it in an EXPORTS statement in the application’s module- 
definition file. 


Parameter ' Description 
hWnd Identifies a window associated with the current task. 
lParam Specifies the same argument that was passed to the Enum- 


Task Windows function. 


Return Value 


The callback function can carry out any desired task. It must return a nonzero value to con- 
tinue enumeration, or a zero value to stop it. 
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EnumWindows 
Syntax BOOL EnumWindows(/pEnumF unc, lParam) 


This function enumerates all parent windows on the screen by passing the handle of each 
window, in turn, to the callback function pointed to by the pEnumFunc parameter. Child 
windows are not enumerated. 


The EnumWindows function continues to enumerate windows until the called function re- 
turns zero or until the last window has been enumerated. 


Parameter Type/Description 


[pEnumFunc FARPROC Is the procedure-instance address of the callback func- 
tion. See the following “Comments” section for details. 


lParam DWORD _ Specifies the value to be passed to the callback function 
for the application’s use. 


Return Value The return value specifies the outcome of the function. It is nonzero if all windows have 
been enumerated. Otherwise, it is zero. 


Comments The address passed as the /pEnumFunc parameter must be created by using the Make- 
ProcInstance function. 


The callback function must use the Pascal calling convention and must be declared FAR. 
The callback function must have the following form: 


Callback Function BOOL FAR PASCAL EnumFunc(hWnd, lParam) 
HWND hWnd; 
DWORD /Param; 


EnumF unc is a placeholder for the application-supplied function name. The actual name 
must be exported by including it in an EXPORTS statement in the application’s module- 
definition file. 


Parameter Description 
hWnd Identifies the window handle. 
lParam Specifies the 32-bit argument of the EnumWindows function. 


Return Value 


The function must return a nonzero value to continue enumeration, or zero to stop it. 
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EqualRect 

Syntax BOOL  EqualRect(/pRect/, lpRect2) 
This function determines whether two rectangles are equal by comparing the coordinates 
of their upper-left and lower-right corners. If the values of these coordinates are equal, 
EqualRect returns a nonzero value; otherwise, it returns zero. 
Parameter Type/Description 
[pRectl ‘LPRECT Points to a RECT data structure that contains the upper- 

left and lower-right corner coordinates of the first rectangle. 
IpRect2 LPRECT Points to a RECT data structure that contains the upper- 
left and lower-right corner coordinates of the second rectangle. 
Ht Return Value The return value specifies whether the specified rectangles are equal. It is nonzero if the 
Ww two rectangles are identical. Otherwise, it is zero. 

EqualRgn 

Syntax BOOL EqualRgn(hSrcRenl, hSrcRgn2) 
This function checks the two given regions to determine whether they are identical. 
Parameter Type/Description 
hSrcRgnl -HRGN Identifies a region. 
hSrcRgn2 HRGN Identifies a region. 

Return Value The return value specifies whether the specified regions are equal. It is nonzero if the two 

~ regions are equal. Otherwise, it is zero. 
Escape 
Syntax int Escape(iDC, nEscape, nCount, lpInData, lpOutData) 


This function allows applications to access facilities of a particular device that are not 
directly available through GDI. Escape calls made by an application are translated and sent 
to the device driver. 
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EscapeCommFunction 


Return Value 


Parameter Type/Description 
hDC HDC Identifies the device context. 
nEscape int Specifies the escape function to be performed. For a complete 


list of escape functions, see Chapter 12, “Printer Escapes,” in 
Reference, Volume 2. 


nCount int Specifies the number of bytes of data pointed to by the /p/n- 
Data parameter. 

IpInData LPSTR Points to the input data structure required for this escape. 

[pOutData LPSTR Points to the data structure to receive output from this 
escape. The /pOutData parameter should be NULL if no data are re- 
turned. ; 


The return value specifies the outcome of the function. It is positive if the function is 
successful except for the QUERYESCSUPPORT escape, which only checks for implemen- 
tation. The return value is zero if the escape is not implemented. A negative value indicates 
an error. The following list shows common error values: 


Value Meaning 
SP_ERROR General error. 
SP_OUTOFDISK Not enough disk space is currently available for spool- 
ing, and no more space will become available. 
SP_OUTOFMEMORY Not enough memory is available for spooling. 
SP_USERABORT User terminated the job through the Print Manager. 
EscapeCommFunction 


Syntax 


int EscapeCommFunction(nCid, nFunc) 


This function directs the communication device specified by the nCid parameter to carry 
out the extended function specified by the nFunc parameter. 


Parameter Type/Description 


nCid int Specifies the communication device to carry out the ex- 
tended function. The OpenComm function returns this value. 


ExcludeClipRect 
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Return Value 


Parameter 


nFunc 


Type/Description 


int Specifies the function code of the extended function. It can 
be any one of the following values: 


Value Description 

CLRDTR Clears the data-terminal-ready (DTR) signal. 
CLRRTS Clears the request-to-send (RTS) signal. 
RESETDEV Resets the device if possible. 

SETDTR Sends the data-terminal-ready (DTR) signal. 
SETRTS Sends the request-to-send (RTS) signal. 
SETXOFF Causes transmission to act as if an XOFF 


character has been received. 


SETXON | Causes transmission to act as if an XON 


character has been received. 


The return value specifies the result of the function. It is zero if it is successful. It is nega- 
tive if the nFunc parameter does not specify a valid function code. 


ExcludeClipRect 
int ExcludeClipRect(iDC, XJ, Y/, X2, Y2) 


Syntax 


This function creates a new clipping region that consists of the existing clipping region 
minus the specified rectangle. 


Parameter 


hDC 
X1 


Yl 


X2 


Type/Description 
HDC Identifies the device context. 


int Specifies the logical x-coordinate of the upper-left corner 
of the rectangle. 


int Specifies the logical y-coordinate of the upper-left corner 
of the rectangle. 


int Specifies the logical x-coordinate of the lower-right corner 
of the rectangle. 
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Parameter Type/Description 
Y2 int Specifies the logical y-coordinate of the lower-right corner 


of the rectangle. 


Return Value The return value specifies the new clipping region’s type. It can be any one of the follow- 


ing values: 

Value Meaning 

COMPLEXREGION The region has overlapping borders. 
ERROR No region was created. 
NULLREGION The region is empty. 
SIMPLEREGION The region has no overlapping borders. 


Comments The width of the rectangle, specified by the absolute value of X2 — X/, must not exceed 
32,767 units. This limit applies to the height of the rectangle as well. 

ExcludeUpdateRgn 

Syntax int ExcludeUpdateRgn(hDC, hWnd) 


This function prevents drawing within invalid areas of a window by excluding an updated 
region in the window from a clipping region. 


Parameter Type/Description 


hDC HANDLE Identifies the device context associated with the 
clipping region. 


hWnd HWND Identifies the window being updated. 


Return Value This value specifies the type of resultant region. It can be any one of the following values: 


Value Meaning 
COMPLEXREGION The region has overlapping borders. 


ERROR No region was created. 
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Value Meaning 
NULLREGION The region is empty. 
SIMPLEREGION The region has no overlapping borders. 


ExitWindows 


Syntax 


Return Value 


BOOL — ExitWindows(dwReserved, wReturnCode) 


This function initiates the standard Windows shutdown procedure. If all applications agree 
to terminate, the Windows session is terminated and control returns to DOS. Windows 
sends the WM_QUERYENDSESSION message to notify all applications that a request 
has been made to terminate Windows. If all applications agree to terminate, Windows 
sends the WM_ENDSESSION message to all applications before exiting. 


Parameter Type/Description 
dwReserved DWORD Is reserved and should be set to zero. 
wReturnCode WORD _ Specifies the return value to be passed to DOS 


when Windows exits. 


The return value is FALSE if one or more applications refused to terminate. The function 
does not return if all applications agree to be terminated. 


ExtDevicelMode 


Syntax 


int ExtDeviceMode(hWnd, hDriver, lpDevModeOutput, IlpDeviceName, IpPort, 
IpDevModelInput, lpProfile, wMode) 


This function retrieves or modifies device initialization information for a given printer 
driver, or displays a driver-supplied dialog box for configuring the printer driver. Printer 


drivers that support device initialization by applications export this ExtDeviceMode so 
that applications can call it. 


Parameter Type/Description 


hWnd HWND Identifies a window. If the application calls Ext- 
DeviceMode to display a dialog box, the specified window 
is the parent of the dialog box. 


4-131 


Parameter 


hDriver 


lpDevModeOutput 


IpDeviceName 


IpPort 


IpDevModelnput 


lpProfile 


wMode 


ExitDeviceMode 


Type/Description 


HANDLE Identifies the device-driver module. The Get- 
ModuleHandle function or LoadLibrary function returns 
a module handle. 


DEVMODE FAR * Points toa DEVMODE data struc- 
ture. The driver writes the initialization information 
supplied in the JpDevModelnput parameter to this structure. 


LPSTR Points to a null-terminated character string that 
contains the name of the printer device, such as “PCL/HP 
LaserJet.” 


LPSTR Points to a null-terminated character string that 
contains the name of the port to which the device is con- 
nected, such as LPT1:. 


DEVMODE FAR * Points toa DEVMODE data struc- 
ture that supplies initialization information to the printer 
driver. 


LPSTR Points to a null-terminated string that contains 
the name of the initialization file which initialization infor- 
mation is recorded in and read from. If this parameter is 
NULL, WIN.INI is the default. 


WORD Specifies a mask of values which determine the 
types of operations the function will perform. If wMode is 
zero, ExtDeviceMode returns the number of bytes required 
by the printer device driver’s DEVMODE structure. Other- 
wise, wMode must be one or more of the following values: 


Value Meaning 

DM_COPY Writes the printer driver’s cur- 
rent print settings to the 
DEVMODE data structure 


identified by IpDevMode- 
Output. The calling application 
must allocate a buffer suffi- 
ciently large to contain the 
information. If this bit is clear, 
IpDevModeOutput can be 
NULL. 
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Return Value 


Comments 


Parameter Type/Description 


Value Meaning 


DM_MODIFY Changes the printer driver’s cur- 
rent print settings to match the 
partial initialization data in the 
DEVMODE data structure 
identified by IpDevModelnput 
before prompting, copying, or 
updating. 


DM_PROMPT Presents the printer driver’s 
Print Setup dialog box and then 
changes the current print set- 
tings to those the user specifies. 


DM_UPDATE Writes the printer driver’s cur- 
rent print settings to the printer 
environment and the WIN.INI 
initialization file. 


If the wMode parameter is.zero, the return value is the size of the DEVMODE data struc- 
ture required to contain the printer driver initialization data. If the function displays the in- 
itialization dialog box, the return value is either IDOK or IDCANCEL, depending on 
which button the user selected. If the function does not display the dialog box and was 
successful, the return value is IDOK. The return value is less than zero if the function 
failed. 


The ExtDeviceMode function is actually part of the printer’s device driver, and not part of 
GDI. To call this function, the application must include the DRIVINT.H file, load the 
printer device driver, and retrieve the address of the function by using the GetProc- 
Address function. The application can then use the address to set up the printer. 


An application can set the wMode parameter to DM_COPY to obtain a DEVMODE data 
structure filled in with the printer driver’s initialization data. The application can then pass 
this data structure to the CreateDC function to set a private environment for the printer 
device context. 
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ExtFloodFill 
Syntax BOOL  ExtFloodFill(“DC, X, Y, crColor, wFillType) 


This function fills an area of the display surface with the current brush. 


If wFillType is set to FLOODFILLBORDER, the area is assumed to be completely 
bounded by the color specified by the crColor parameter. The ExtFloodFill function 
begins at the point specified by the X and Y parameters and fills in all directions to the 
color boundary. 


If wFillType is set to FLOODFILLSURFACE, the ExtFloodFill function begins at the 
point specified by X and Y and continues in all directions, filling all adjacent areas contain- 
ing the color specified by crColor. | 


Parameter Type/Description 

hDC HDC Identifies the device context. 

Xx int Specifies the logical x-coordinate of the point where filling 
begins. 

Y int Specifies the logical y-coordinate of the point where filling 
begins. 

crColor COLORREF _ Specifies the color of the boundary or of the area to 
be filled. The interpretation of crColor depends on the value of the 
wFillType parameter. 

wFillType WORD Specifies the type of flood fill to be performed. It must be 
one of the following values: 
Value Meaning 
FLOODFILLBORDER The fill area is bounded by the 


color specified by crColor. This 
style is identical to the filling 
performed by the FloodFill 
function. 


FLOODFILLSURFACE The fill area is defined by the 
color specified by crColor. 
Filling continues outward in all 
directions as long as the color is 
encountered. This style is useful 
for filling areas with multi- 
colored boundaries. 
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Return Value The return value specifies the outcome of the function. It is nonzero if the function is 
successful. It is zero if: 


= = The filling could not be completed 


= The given point has the boundary color specified by crColor (if FLOOD- 
FILLBORDER was requested) 


= ©The given point does not have the color specified by crColor (if FLOOD- 
FILLSURFACE was requested) 


= The point is outside the clipping region 


Comments Only memory device contexts and devices that support raster-display technology support 
the ExtFloodFill function. For more information, see the RC_BITBLT raster capability in 
the GetDeviceCaps function, later in this chapter. 

ie : 

be 
Ml 

- ExtTextOut | 

Syntax BOOL ExtTextOut(hDC, X, Y, wOptions, lpRect, IpString, nCount, IpDx) 


This function writes a character string, within a rectangular region on the specified display, 
using the currently selected font. The rectangular region can be opaque (filled with the cur- 
rent background color) and it can be a clipping region. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
Xx int Specifies the logical x-coordinate of the origin of the character 


cell for the first character in the specified string. 


Y int Specifies the logical y-coordinate of the origin of the character 
cell for the first character in the specified string. 


wOptions WORD Specifies the rectangle type. It can be one or both of the 
c 9 following values, or neither: 


ETO_CLIPPED 
ETO_OPAQUE 


The ETO_CLIPPED value specifies that Windows will clip text to 
the rectangle. The ETO_OPAQUE value specifies that the current 
background color fills the rectangle. 


IpRect LPRECT Points to a RECT data structure. The /pRect parameter 
can be NULL. 
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ExtTextOut 


Return Value 


Comments 


Parameter Type/Description 

IpString LPSTR Points to the spetified character string. 

nCount int Specifies the number of characters in the string. 

IpDx LPINT Points to an array of values that indicate the distance be- 


tween origins of adjacent character cells. For instance, /pDx[i] logical 
units will separate the origins of character cell i and character cell i + 
1. 


The return value specifies whether or not the string is drawn. It is nonzero if the string is 
drawn. Otherwise, it is zero. 


If IpDx is NULL, the function uses the default spacing between characters. 


The character-cell origins and the contents of the array pointed to by the /pDx parameter 
are given in logical units. A character-cell origin is defined as the upper-left corner of the 
character cell. 


By default, the current position is not used or updated by this function. However, an appli- 
cation can call the SetTextAlign function with the wF/ags parameter set to TA_UP- 
DATECP to permit Windows to use and update the current position each time the 
application calls ExtTextOut for a given device context. When this flag is set, Windows ig- 
nores the X and Y parameters on subsequent ExtTextOut calls. 


FatalAppExit 4-136 


FatalAppExit 
Syntax VOID FatalAppExit(wAction, lpMessageText) 


This function displays a message containing the text specified by the pMessageText para- 
meter and terminates the application when the message box is closed. When called under 
the debugging version of Windows, the message box gives the user the opportunity to ter- 
minate the application or to return to the caller. 


Parameter Type/Description 
wAction WORD Is reserved and must be set to 0. 
IpMessageText LPSTR Points to a character string that is displayed in the 


message box. The message is displayed on a single line. To ac- 
commodate low-resolution displays, the string should be no 
more than 35 characters in length. 


Return Value None. 


Comments An application that encounters an unexpected error should terminate by freeing all its 
memory and then returning from its main message loop. It should call FatalAppExit only 
when it is not capable of terminating any other way. FatalAppExit may not always free an 
application’s memory or close its files, and it may cause a general failure of Windows. 


FatalExit 
Syntax void FatalExit(Code) 


This function displays the current state of Windows on the debugging monitor and prompts 
for instructions on how to proceed. The display includes an error code, the Code parame- 
ter, followed by a symbolic stack trace, showing the flow of execution up to the point of 
call. 


An application should call this function only for debugging purposes; it should not call the 
function in a retail version of the apphcanon: Calling this function in the retail version will 
terminate the application. 


Parameter Type/Description 


Code int Specifies the error code to be displayed. 


Return Value None. 
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Comments The FatalExit function prompts the user to respond to an “‘Abort, Break or Ignore” 
message. FatalExit processes the response as follows: 
Response Description 
A (Abort) Terminates Windows. 
B (Break) Simulates a non-maskable interrupt (NMJ) to enter the debugger. 
I (Ignore) Returns to the caller. 
The FatalExit function is for debugging only. 
An application should call this function whenever the application detects a fatal error. All 
input and output is received and transmitted through the computer’s auxiliary port (AUX) 
or through the debugger if a debugger is installed. 
FillRect 
Syntax int FillRect(hDC, IpRect, hBrush) 


Return Value 


Comments 


This function fills a given rectangle by using the specified brush. The FillRect function 
fills the complete rectangle, including the left and top borders, but does not fill the right 
and bottom borders. 


Parameter Type/Description 

hDC HDC Identifies the device context. 

lpRect LPRECT Points to a RECT data structure that contains the logical 
coordinates of the rectangle to be filled. 

hBrush HBRUSH Identifies the brush used to fill the rectangle. 


Although the FillRect function return type is an integer, the return value is not used and 
has no meaning. 


The brush must have been created previously by using either the CreateHatchBrush, 
CreatePatternBrush, or CreateSolidBrush function, or retrieved using the GetStockOb- 
ject function. 


When filling the specified rectangle, the FillRect function does not include the rectangle’s 
right and bottom sides. GDI fills a rectangle up to, but does not include, the right column 
and bottom row, regardless of the current mapping mode. 


FillRgn 
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FillRgn 
Syntax 


Return Value 


FindAtom 
Syntax 


Return Value 


FillRect compares the values of the top, bottom, left, and right fields of the specified 
rectangle. If bottom is less than or equal to top, or if right is less than or equal to left, the 
rectangle is not drawn. 


BOOL | FillRgn(ADC, hRgn, hBrush) 


This function fills the region specified by the hARgn parameter with the brush specified by 
the ABrush parameter. 


Parameter Type/Description 

hDC : HDC Identifies the device context. 

hRen HRGN Identifies the region to be filled. The coordinates for the 
given region are specified in device units. 

hBrush HBRUSH Identifies the brush to be used to fill the region. 


The return value specifies the outcome of the function. It is nonzero if the function is 
successful. Otherwise, it is zero. 


ATOM _ FindAtom(ipString) 


This function searches the atom table for the character string pointed to by the ipString par- 
ameter and retrieves the atom associated with that string. 


Parameter Type/Description 


[pString LPSTR _ Points to the character string to be searched for. The string 
must be null-terminated. 


The return value identifies the atom associated with the given string. It is NULL if the 
string is not in the table. 
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FindResource ’ 
Syntax HANDLE = FindResource(hInstance, lpName, IpType) 
This function determines the location of a resource in the specified resource file. The 
IpName and IpType parameters define the resource name and type, respectively. 
Parameter Type/Description 
hInstance HANDLE Identifies the instance of the module whose executable 
file contains the resource. 
IpName LPSTR Points to a null-terminated character string that represents 
the name of the resource. 
lpType LPSTR Points to a null-terminated character string that represents 
the type name of the resource. For predefined resource types, the 
[pType parameter should be one of the following values: 
Value Meaning 
RT_ACCELERATOR Accelerator table 
RT_BITMAP Bitmap resource 
RT_DIALOG — Dialog box 
RT_FONT Font resource 
RT_FONTDIR Font directory resource 
RT_MENU Menu resource 
RT_RCDATA User-defined resource (raw data) 
Return Value The return value identifies the named resource. It is NULL if the requested resource cannot 
be found. 
Comments An application must not call FindResource and the LoadResource function to load 


cursor, icon, and string resources. Instead, it must load these resources by calling the fol- 
lowing functions: 

= LoadCursor 

= LoadIcon 


= LoadString 
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FindWindow 
Syntax 


Return Value 


An application can call FindResource and LoadResource to load other predefined 
resource types. However, it is recommended that the application load the corresponding 
resources by calling the following functions: 


= LoadAccelerators 
= LoadBitmap 
# LoadMenu 


If the high-order word of the JpName or [pType parameter is zero, the low-order word 
specifies the integer ID of the name or type of the given resource. Otherwise, the parame- 
ters are long pointers to null-terminated character strings. If the first character of the string 
is a pound sign (#), the remaining characters represent a decimal number that specifies the 
integer ID of the resource’s name or type. For example, the string #258 represents the in- 
teger ID 258. 


To reduce the amount of memory required for the resources used by an application, the 
application should refer to the resources by integer ID instead of by name. 


HWND _FindWindow(/pClassName, lpWindowName) 


This function returns the handle of the window whose class is given by the IpClassName 
parameter and whose window name, or caption, is given by the /pWindowName parameter. 


Parameter Type/Description 


IpClassName LPSTR Points to a null-terminated character string that speci- 
fies the window’s class name. If JpClassName is NULL, all class 
names match. 


IpWindowName LPSTR Points to a null-terminated character string that speci- 
fies the window name (the window’s text caption). If 
lpWindowName is NULL, all window names match. 


The return value identifies the window that has the specified class name and window 
name. It is NULL if no such window is found. 
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FlashWindow 


FlashWindow 
Syntax 


Return Value 


Comments 


FloodFill 
Syntax 


BOOL = FlashWindow(hWnd, bInvert) 


This function “flashes” the given window once. Flashing a window means changing the ap- 
pearance of its caption bar as if the window were changing from inactive to active status, 
or vice versa. (An inactive caption bar changes to an active caption bar; an active caption 
bar changes to an inactive caption bar.) 


Typically, a window is flashed to inform the user that the window requires attention, but 
that it does not currently have the input focus. 


Parameter Type/Description 


hWnd HWND _Identifies the window to be flashed. The window can be 
either open or iconic. 


bInvert BOOL Specifies whether the window is to be flashed or returned 
to its original state. The window is flashed from one state to the other 
if the b/nvert parameter is nonzero. If the b/nvert parameter is zero, 
the window is returned to its original state (either-active or inactive). 


The return value specifies the window’s state before call to the FlashWindow function. It 
is nonzero if the window was active before the call. Otherwise, it is zero. 


The FlashWindow function flashes the window only once; for successive flashing, the 
application should create a system timer. 


The b/nvert parameter should be zero only when the window is getting the input focus and 
will no longer be flashing; it should be nonzero on successive calls while waiting to get the 
input focus. 


This function always returns a nonzero value for iconic windows. If the window is iconic, 
FlashWindow will simply flash the icon; b/nvert is ignored for iconic windows. 


BOOL  FloodFill(ADC, X, Y, crColor) 


This function fills an area of the display surface with the current brush. The area is as- 
sumed to be bounded as specified by the crColor parameter. The FloodFill function begins 
at the point specified by the X and Y parameters and continues in all directions to the color 
boundary. 
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Parameter Type/Description 

hDC HDC Identifies the device context. 

X int Specifies the logical x-coordinate of the point where filling 
begins. 

Y int Specifies the logical y-coordinate of the point where filling 
begins. 

crColor COLORREF Specifies the color of the boundary. 

Return Value The return value specifies the outcome of the function. It is nonzero if the function is 


successful. It is zero if the filling could not be completed, the given point has the boundary 
color specified by crColor, or the point is outside the clipping region. 


Comments Only memory device contexts and devices that support raster-display technology support 
the FloodFill function. For more information, see the RC_BITBLT raster capability in the 
GetDeviceCaps function, later in this chapter. 


FlushComm 
Syntax int FlushComm(nCid, nQueue) 
This function flushes all characters from the transmit or receive queue of the communica- 
tion device specified by the nCid parameter. The nQueue parameter specifies which queue 
is to be flushed. 
Parameter Type/Description 
nCid int Specifies the communication device to be flushed. The Open- 
Comm function returns this value. 
nQueue int Specifies the queue to be flushed. If nQueue is zero, the trans- 
mit queue is flushed. If it is 1, the receive queue is flushed. 
Return Value The return value specifies the result of the function. It is zero if it is successful. It is nega- 


tive if nCid is not a valid device, or if nQueue is not a valid queue. 
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FrameRect 
Syntax int FrameRect(hDC, IpRect, hBrush) 


This function draws a border around the rectangle specified by the /pRect parameter. The 
FrameRect function uses the given brush to draw the border. The width and height of the 
border is always one logical unit. 

Parameter Type/Description 


hDC HDC Identifies the device context of the window. 


IpRect LPRECT Points to a RECT data structure that contains the logical 
coordinates of the upper-left and lower-right corners of the rectangle. 


hBrush HBRUSH Identifies the brush to be used for framing the rectangle. 


Return Value Although the return value type is integer, its contents should be ignored. 


Comments The brush identified by the hBrush parameter must have been created previously by using 
the CreateHatchBrush, CreatePatternBrush, or CreateSolidBrush function. 


If the bottom field is less than or equal to the top field, or if right is less than or equal to 
left, the rectangle is not drawn. 


FrameRgn 
Syntax BOOL  FrameRgn(iDC, hRgn, hBrush, nWidth, nHeight) 


This function draws a border around the region specified by the hRgn parameter, using the 
brush specified by the HBrush parameter. The nWidth parameter specifies the width of the 
border in vertical brush strokes; the nHeight parameter specifies the height in horizontal 
brush strokes. - 


Parameter Type/Description 
hDC HDC Identifies the device context. 
hRgn HANDLE Identifies the region to be enclosed in a border. The 


coordinates for the given region are specified in device units. 
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Parameter Type/Description 
hBrush HBRUSH Identifies the brush to be used to draw the border. 
nWidth int Specifies the width in vertical brush strokes (in logical units). 
nHeight int Specifies the height in horizontal brush strokes (in logical 
units). 


Return Value 


FreeLibrary 
Syntax 


Return Value 


The return value specifies the outcome of the function. It is nonzero if the function is 
successful. Otherwise, it is zero. 


void FreeLibrary(hLibModule) 


This function decreases the reference count of the loaded library module by one. When the 
reference count reaches zero, the memory occupied by the module is freed. 


Parameter Type/Description 


hLibModule HANDLE Identifies the loaded library module. 


None. 


FreeModule 


Syntax 


‘Return Value 


void FreeModule(iModule) 


This function decreases the reference count of the loaded module by one. When the 
reference count reaches zero, the memory occupied by the module is freed. 


Parameter Type/Description 
hModule HANDLE Identifies the loaded module. 
None. 
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FreeProcinstance 
Syntax void FreeProcInstance(/pProc) 


Return Value 


Comments 


FreeResource 
~ Syntax 


Return Value 


This function frees the function specified by the /pProc parameter from the data segment 
bound to it by the MakeProcInstance function. 


Parameter Type/Description 

IpProc FARPROC Is the procedure-instance address of the function to be 
freed. It must have been created previously by using the Make- 
ProcInstance function. 

None. 


After freeing a procedure instance, attempts to call the function using the freed procedure- 
instance address will result in an unrecoverable error. 


BOOL FreeResource(iResData) 


This function removes a loaded resource from memory by freeing the allocated memory 
occupied by that resource. 


The FreeResource function does not actually free the resource until the reference count is 
zero (that is, the number of calls to the function equals the number of times the application 
called the LoadResource function for this resource). This ensures that the data remain in 
memory for the application to use. 


Parameter Type/Description 

hResData HANDLE Identifies the data associated with the resource. The 
handle is assumed to have been created by using the LoadResource 
function. 


The return value specifies the outcome of the function. The return value is nonzero if the 
function has failed and the resource has not been freed. The return value is zero if the func- 
tion is successful. 


te 
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FreeSelector 


Syntax 


Return Value 


Comments 


WORD _sFreeSelector(wSelector) 


This function frees a selector originally allocated by the AllocSelector, AllocCStoDS- 
Alias, or AllocDStoCSAlias functions. After the application calls this function, the selec- 
tor is invalid and must not be used. 


Parameter Type/Description 


wSelector WORD _ Specifies the selector to be freed. 


The return value is NULL if the function was successful. Otherwise, it is the selector 
specified by the wSelector parameter. 


An application should not use this function unless it is absolutely necessary. Use of this 


function violates preferred Windows programming practices. 
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GetActiveWindow 
Syntax HWND_ GetActiveWindow( ) 


Return Value 


This function retrieves the window handle of the active window. The active window is 
either the window that has the current input focus, or the window explicitly made active by 
the SetActive Window function. 


This function has no parameters. 


The return value identifies the active window. 


GetAspectRatioFilter 


Syntax 


Return Value 


DWORD  GetAspectRatioFilter(ADC) 


This function retrieves the setting for the current aspect-ratio filter. The aspect ratio is the 
ratio formed by a device’s pixel width and height. Information about a device’s aspect ratio 
is used in the creation, selection, and displaying of fonts. Windows provides a special fil- 
ter, the aspect-ratio filter, to select fonts designed for a particular aspect ratio from all of 
the available fonts. The filter uses the aspect ratio specified by the SetMapperFlags func- 
tion, 


Parameter Type/Description 
hDC HDC Identifies the device context that contains the specfied aspect 
ratio. 


The return value specifies the aspect ratio used by the current aspect-ratio filter. The x- 
coordinate of the aspect ratio is contained in the high-order word, and the y-coordinate is 
contained in the low-order word. 


GetAsyncKeyState 


Syntax 


int GetAsyncKeyState(vKey) 


This function determines whether a key is up or down at the time the function is called, 
and whether the key was pressed after a previous call to the GetAsyncKeyState function. 
If the most significant bit of the return value is set, the key is currently down; if the least 
significant bit is set, the key was pressed after a previous call to the function. 
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Return Value 


Parameter Type/Description 


vKey int Specifies one of 256 possible virtual-key code values. 


The return value specifies whether the key was pressed since the last call to GetAsyncKey- 
State and whether the key is currently up or down. If the most significant bit is set, the key 
is down, and if the least significant bit is set, the key was pressed after a preceding 
GetAsyncKeyState call. 


GetAtomHandle 


Syntax 


Return Value 


GetAtomName 
Syntax 


Return Value 


HMEM_ GetAtomHandle(wAtom) 


This function retrieves a handle (relative to the local heap) of the string that corresponds to 
the atom specified by the wAtom parameter. 


Parameter Type/Description 


wAtom WORD Specifies an unsigned integer that identifies the atom 
whose handle is to be retrieved. 


The return value identifies the given atom’s string. It is zero if no such atom exists. 


WORD GetAtomName(nAtom, IpBuffer, nSize) 


This function retrieves a copy of the character string associated with the nAtom parameter 
and places it in the buffer pointed to by the /pBuffer parameter. The nSize parameter speci- 
fies the maximum size of the buffer. 


Parameter Type/Description 

nAtom ATOM. Identifies the character string to be retrieved. 

IpBuffer LPSTR Points to the buffer that is to receive the character string. 
nSize int Specifies the maximum size (in bytes) of the buffer. 


The return value specifies the actual number of bytes copied to the buffer. It is zero if the 
specified atom is not valid. 
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GetBitmapBits 


GetBitmapBits 
Syntax 


Return Value 


DWORD GetBitmapBits(iBitmap, dwCount, IpBits) 


This function copies the bits of the specified bitmap into the buffer that is pointed to by the 
IpBits parameter. The dwCount parameter specifies the number of bytes to be copied to the 
buffer. The GetObject function should be used to determine the correct dwCount value for 
the given bitmap. 


Parameter Type/Description 

hBitmap HBITMAP Identifies the bitmap. 

dwCount DWORD Specifies the number of bytes to be copied. 

IpBits LPSTR Long pointer to the buffer that is to receive the bitmap. 


The bitmap is an array of bytes. The bitmap byte array conforms to a 
structure where horizontal scan lines are multiples of 16 bits. 


The return value specifies the actual number of bytes in the bitmap. It is zero if there is an 
error. 


GetBitmapDimension 


Syntax 


Return Value 


DWORD GetBitmapDimension(hBitmap) 


This function returns the width and height of the bitmap specified by the hBitmap parame- 
ter. The height and width is assumed to have been set previously by using the SetBit- 


‘mapDimension function. 


Parameter Type/Description 


hBitmap HBITMAP Identifies the bitmap. 


The return value specifies the width and height of the bitmap, measured in tenths of milli- 
meters. The height is in the high-order word, and the width is in the low-order word. If the 
bitmap width and height have not been set by using SetBitmapDimension, the return 
value is zero. 
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GetBkColor 

Syntax DWORD GetBkColor(hDC) 
This function returns the current background color of the specified device. 
Parameter Type/Description 
hDC HDC Identifies the device context. 

Return Value The return value specifies an RGB color value that names the current background color. 

GetBkMode 

Syntax int GetBkMode(hDC) 
This function returns the background mode of the specified device. The background mode 
is used with text, hatched brushes, and pen style that is not a solid line. 

i Parameter Type/Description 
‘ hDC HDC Identifies the device context. 

Return Value The return value specifies the current background mode. It can be OPAQUE or TRANS- 
PARENT. 

GetBrushOrg 

Syntax DWORD_ GetBrushOrg(hDC) 
This function retrieves the current brush origin for the given device context. 
Parameter Type/Description 
hDC HDC Identifies the device context. 

Return Value The return value specifies the current origin of the brush. The x-coordinate is in the low 


word, and the y-coordinate is in the high word. The coordinates are assumed to be in 
device units. 


Comments The initial brush origin is at the coordinate (0,0). 
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GetBValue 


GetBValue 
Syntax 


Return Value 


Comments 


GetCapture 
Syntax 


Return Value 


BYTE GetBValue(rgbColor) 


This macro extracts the blue value from an RGB color value. 


Parameter Type/Description 


rgbColor DWORD Specifies a red, a green, and a blue color field, each 
specifying the intensity of the given color. 


_ The return value specifies a byte that contains the blue value of the rgbColor parameter. 


The value OFFH corresponds to the maximum intensity value for a single byte; OOOH corre- 
sponds to the minimum intensity value for a single byte. 


HWND GetCapture( ) 


This function retrieves a handle that identifies the window that has the mouse capture. 
Only one window has the mouse capture at any given time; this window receives mouse 
input whether or not the cursor is within its borders. 


This function has no parameters. 


The return value identifies the window that has the mouse capture; it is NULL if no 
window has the mouse capture. 


Comments A window receives the mouse capture when its handle is passed as the hWnd parameter of 
the SetCapture function. 

GetCaretBlinkTime 

Syntax WORD  GetCaretBlinkTime( ) 


Return Value 


This function retrieves the caret blink rate. The blink rate is the elapsed time in millisec- 
onds between flashes of the caret. 


This function has no parameters. 


The return value specifies the blink rate (in milliseconds). 
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GetCaretPos 
Syntax 


Return Value 


Comments 


GetCharWidth 
Syntax 


Return Value 


void GetCaretPos(/pPoint) 


This function retrieves the caret’s current position (in screen coordinates), and copies them 
to the POINT structure pointed to by the /pPoint parameter. 


Parameter Type/Description 


IpPoint LPPOINT Points to the POINT structure that is to receive the 
screen coordinates of the caret. 


None. 


The caret position is always given in the client coordinates of the window that contains the 
caret. 


BOOL GetCharWidth(ADC, wFirstChar, wLastChar, lpBuffer) 


This function retrieves the widths of individual characters in a consecutive group of 
characters from the current font. For example, if the wFirstChar parameter identifies the 
letter a and the wLastChar parameter identifies the letter z, the GetCharWidth function re- 
trieves the widths of all lowercase characters. The function stores the values in the buffer 
pointed to by the /pBuffer parameter. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
wFirstChar WORD Specifies the first character in a consecutive group of 


characters in the current font. 


wLastChar WORD Specifies the last character in a consecutive group of 
characters in the current font. 


lpBuffer LPINT Points to a buffer that will receive the width values for a 
consecutive group of characters in the current font. 


The return value specifies the outcome of the function. It is nonzero if the function is 
successful. Otherwise, it is zero. 


\ 
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Comments 


If a character in the consecutive group of characters does not exist in a particular font, it 
will be assigned the width value of the default character. 


GetClassInfo 


Syntax 


Return Value 


Comments 


GetClassLong 
Syntax 


BOOL = GetClassInfo(hInstance, IpClassName, IpWndClass) 


This function retrieves information about a window class. The h/nstance parameter identi- 
fies the instance of the application that created the class, and the JpClassName parameter 
identifies the window class. If the function locates the specified window class, it copies the 
WNDCLASS data used to register the window class to the WNDCLASS data structure 
pointed to by /pWndClass. 


Parameter Type/Description 


hInstance HANDLE Identifies the instance of the application that created the 
class. To retrieve information on classes defined by Windows (such 
as buttons or list boxes), set hJnstance to NULL. 


IpClassName LPSTR Points to a null-terminated string that contains the name of 
the class to find. If the high-order word of this parameter is NULL, 
the low-order word is assumed to be a value returned by the 
MAKEINTRESOURCE macro used when the class was created. 


lpWndClass LPWNDCLASS Points to the WNDCLASS structure to which 
the function will copy the class information. . 


The return value is TRUE if the function found a matching class and successfully copied 
the data; the return value is FALSE if the function did not find a matching class. 


The IpszClassName, IpszMenuName, and hInstance fields in the WNDCLASS data 
structure are not returned by this function. The menu name is not stored internally and can- 
not be returned. The class name is already known since it is passed to this function. The 
GetClassInfo function returns all other fields with the values used when the class was 
registered. 


LONG  GetClassLong(hWnd, nIndex) 


This function retrieves the long value specified by the n/Jndex parameter from the WND- 
CLASS structure of the window specified by the hWnd parameter. 
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Parameter Type/Description 
hWnd HWND Identifies the window. 
nIndex int Specifies the byte offset of the value to be retrieved. It can also 


be the following value: 


Value Meaning 
GCL_WNDPROC Retrieves a long pointer to the window 
function. 
Return Value -—“' The return value specifies the value retrieved from the WNDCLASS structure. 
Comments To access any extra four-byte values allocated when the window-class structure was 


created, use a positive byte offset as the index specified by the n/ndex parameter. The first 
four-byte value in the extra space is at offset zero, the next four-byte value is at offset 4, 
and so on. 


GetClassName 
Syntax int GetClassName(hWnd, lpClassName, nMaxCount) 


This function retrieves the class name of the window specified by the hWnd parameter. 


Parameter Type/Description 

hWnd HWND Identifies the window whose class name is to be re- 
trieved. 

lpClassName LPSTR Points to the buffer that is to receive the class name. 

nMaxCount int Specifies the maximum number of bytes to be stored in the 


IpClassName parameter. If the actual name is longer, a truncated 
name is copied to the buffer. 


Return Value The return value specifies the number of characters actually copied to JpClassName. The 
return value is zero if the specified class name is not valid. 
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GetClassWord 
Syntax 


Return Value 


Comments 


WORD GetClassWord(hWnd, nIndex) 


This function retrieves the word that is specified by the nJndex parameter from the WND- 


GetClassWord 


CLASS structure of the window specified by the hWnd parameter. 


Parameter 


hWnd 


nIndex 


Type/Description 


HWND Identifies the window. 


int Specifies the byte offset of the value to be retrieved. It can also 


be one of the following values: 


Value 


GCW_CBCLSEXTRA 


GCW_CBWNDEXTRA 


GCW_HBRBACKGROUND 


GCW_HCURSOR 
GCW_HICON 
GCW_HMODULE 


GCW_STYLE 


Meaning 


Tells how many bytes of addi- 
tional class information you 
have. For information on how 
to access this memory, see the 
following “Comments” section. 


Tells how many bytes of addi- 
tional window information you 
have. For information on how 
to access this memory, see the 
following “Comments” section. 


Retrieves a handle to the back- 
ground brush. 


Retrieves a handle to the cursor. 
Retrieves a handle to the icon. 


Retrieves a handle to the mod- 
ule. 


Retrieves the window-class 
style bits. 


The return value specifies the value retrieved from the WNDCLASS structure. 


To access any extra two-byte values allocated when the window-class structure was 


created, use a positive byte offset as the index specified by the n/ndex parameter, starting 
at zero for the first two-byte value in the extra space, 2 for the next two-byte value and so 


on. 
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GetClientRect 
Syntax 


void GetClientRect(hWnd, lpRect) 


This function copies the client coordinates of a window’s client area into the data structure 
pointed to by the /pRect parameter. The client coordinates specify the upper-left and lower- 
right corners of the client area. Since client coordinates are relative to the upper-left 
corners of a window’s client area, the coordinates of the upper-left corner are (0,0). 


Parameter Type/Description 
hWnd HWND Identifies the window associated with the client area. 
IpRect LPRECT Points to a RECT data structure. 

Return Value None. 

GetClipboardData 


Syntax 


Return Value 


Comments 


HANDLE GetClipboardData(wFormat) 


This function retrieves data from the clipboard in the format given by the wFormat parame- 
ter. The clipboard must have been opened previously. 


Parameter -Type/Description 


wFormat WORD Specifies a data format. For a description of the data for- 
mats, see the SetClipboardData function, later in this chapter. 


The return. value identifies the memory block that contains the data from the clipboard. 
The handle type depends on the type of data specified by the wFormat parameter. It is 
NULL if there is an error. 


The available formats can be enumerated in advance by using the EnumClipboardFor- 
mats function. 


The data handle returned by GetClipboardData is controlled by the clipboard, not by the 
application. The application should copy the data immediately, instead of relying on the 
data handle for long-term use. The application should not free the data handle or leave it 
locked. 


Windows supports two formats for text, CF_TEXT and CF_OEMTEXT. CF_TEXT is the 
default Windows text clipboard format, while Windows uses the CF_OEMTEXT format 
for text in non-Windows applications. If you call GetClipboardData to retrieve data in 
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GetClipboardFormatName 


one text format and the other text format is the only available text format, Windows auto- 
matically converts the text to the requested format before supplying it to your application. 


If the clipboard contains data in the CF_PALETTE (logical color palette) format, the appli- 
cation should assume that any other data in the clipboard is realized against that logical 
palette. 


GetClipboardFormatName 


Syntax 


Return Value 


int GetClipboardFormatName(wFormat, lpFormatName, nMaxCount) 


This function retrieves from the clipboard the name of the registered format specified by 
the wFormat parameter. The name is copied to the buffer pointed to by the /pFormatName 
parameter. 


Parameter Type/Description 

wFormat WORD Specifies the type of format to be retrieved. It must 
not specify any of the predefined clipboard formats. 

IpFormatName LPSTR Points to the buffer that is to receive the format name. 

nMaxCount int Specifies the maximum length (in bytes) of the string to be 


copied to the buffer. If the actual name is longer, it is truncated. 


The return value specifies the actual length of the string copied to the buffer. It is zero if 
the requested format does not exist or is a predefined format. 


GetClipboardOwner 


Syntax 


Return Value 


Comments 


HWND  GetClipboardOwner( ) 


This function retrieves the window handle of the current owner of the clipboard. 


This function has no parameters. 


The return value identifies the window that owns the clipboard. It is NULL if the clipboard 
is not owned. 


The clipboard can still contain data even if the clipboard is not currently owned. 
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GetClipboardViewer | 
Syntax . HWND  GetClipboardViewer( ) 


This function retrieves the window handle of the first window in the clipboard-viewer 
chain. 


This function has no parameters. 


Return Value The return value identifies the window currently responsible for displaying the clipboard. 
It is NULL if there is no viewer. 


GetClipBox 
Syntax int GetClipBox(DC, IpRect) 
This function retrieves the dimensions of the tightest bounding rectangle around the cur- 
rent clipping boundary. The dimensions are copied to the buffer pointed to by the /pRect 
. parameter. 
Parameter Type/Description 
hDC HDC Identifies the device context. 
IpRect LPRECT Points to the RECT data structure that is to receive the 
rectangle dimensions. | 
Return Value The return value specifies the clipping region’s type. It can be any one of the following 
values: 
Value Meaning 


COMPLEXREGION Clipping region has overlapping borders. 
ERROR Device context is not valid. 
NULLREGION Clipping region is empty. 
SIMPLEREGION Clipping region has no overlapping borders. 
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GetCodeHandle 


Syntax 


Return Value 


Comments 


HANDLE GetCodeHandle(/pProc) 


This function determines which code segment contains the function pointed to by the 
IpProc parameter. 


Parameter Type/Description 


IpProc FARPROC Is a procedure-instance address. 


The return value identifies the code segment that contains the function. 


If the code segment that contains the function is already loaded, the GetCodeHandle func- 
tion marks the segment as recently used. If the code segment is not loaded, GetCode- 
Handle attempts to load it. Thus, an application can use this function to attempt to preload 
one or more segments needed to perform a particular task. 


GetCodelnfo 


Syntax 


Return Value 


Comments 


void GetCodelInfo(/pProc, lpSegInfo) 


This function retrieves a pointer to an array of 16-bit values containing information about 
the code segment that contains the function pointed to by the /pProc parameter. 


Parameter Type/Description 


IpProc FARPROC Is the address of the function in the segment for 
. which information is to be retrieved. Instead of a segment:offset 
address, this value can also be in the form of a module handle and 
segment number. The GetModuleHandle function returns the handle 
of a named module. 


IpSegInfo LPVOID _ Points to an array of four 32-bit values that will be filled 
with information about the code segment. See the following “Com- 
ments” section for a description of the values in this array. 


None. 


The /pSegInfo parameter points to an array of four 32-bit values that contains such informa- 
tion as the location and size of the segment and its attributes. The following list describes 
each of these values: ~ 


GetCodelnfo 
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Offset 


Description 


Specifies the logical-sector offset (in bytes) to the contents of the segment 
data, relative to the beginning of the file. Zero means no file data is availa- 
ble. 


Specifies the length of the segment in the file (in bytes). Zero means 64K. 


Contains flags which specify attributes of the segment. The following list de- 
scribes these flags: 


Bit Meaning 

0-2 Specifies the segment type. If bit 0 is set to 1, the segment is a 
data segment. Otherwise, the segment is a code segment. 

> Specifies whether segment data is iterated. When this bit set to 
1, the segment data is iterated. 

4 Specifies whether the segment is moveable or fixed. When this 
bit is set to 1, the segment is moveable. Otherwise, it is fixed. 

5 Is not returned. 

6 Is not returned. 

7 Specifies whether the segment is a read-only data segment or an 


execute-only code segment. If this bit is set to 1 and the segment 
is acode segment, the segment is an execute-only segment. If 
this bit is set to zero and the segment is a data segment, it is a 
read-only segment. 


8 Specifies whether the segment has associated relocation informa- 
tion. If this bit is set to 1, the segment has relocation 
information. Otherwise, the segment does not have relocation 
information. 


9 Specifies whether the segment has debugging information. If 
this bit is set to 1, the segment has debugging information. Other- 
wise, the segment does not have debugging information. 


10-11 Is not returned. 
12-15 Is not returned. 


Specifies the total amount of memory allocated for the segment. This 
amount may exceed the actual size of the segment. Zero means 65,536. 
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GetCommeError 
Syntax 


Return Value 


int GetCommError(nCid, [pStat) 


In case of a communications error, Windows locks the communications port until the error 
is Cleared by using the GetCommError function. This function fills the status buffer 
pointed to by the /pStat parameter with the current status of the communication device 
specified by the nCid parameter. It also returns the error codes that have occurred since the 
last GetCommError call. If /pStat is NULL, only the error code is returned. For a list of 
the error codes, see Table 4.8, “Communications Error Codes.” 


Parameter 


nCid 


IpStat 


Type/Description 


int Specifies the communication device to be examined. The Open- 
Comm function returns this value. 


COMSTAT FAR * Points to the COMSTAT structure that is to re- 
ceive the device status. The structure contains information about a 
communication device. 


The return value specifies the error codes returned by the most recent communications 
function. It can be a combination of one or more of the values given in Table 4.8. 


Table 4.8 Communications Error Codes 


Value — 


CE_BREAK 
CE_CTSTO 


CE_DNS 
CE_DSRTO 


CE_FRAME 
CE_IOE 
CE_MODE 


CE_OOP 
CE_OVERRUN 


CE_PTO 
CE_RLSDTO 


Meaning 


The hardware detects a break condition. 


Clear-to-send timeout. CTS is low for the duration specified by 
CtsTimeout while trying to transmit a character. 


The parallel device is not selected. 


Data-set-ready timeout. DSR is low for the duration specified by 
DsrTimeout while trying to transmit a character. 


The hardware detects a framing error. 
An I/O error occurs while trying to communicate with a parallel device. 


Requested mode is not supported, or the nCid parameter is invalid. If 
set, this is the only valid error. 


The parallel device signals that it is out of paper. 


A character is not read from the hardware before the next character ar- 
rives. The character is lost. 


Timeout occurs while trying to communicate with a parallel device. 


Receive-line-signal-detect timeout. RLSD is low for the duration 
specified by RlsdTimeout while trying to transmit a character. 
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Table 4.8 Communications Error Codes (continued) 


Value Meaning 
CE_RXOVER Receive queue overflow. There is either no room in the input queue or a 
character is received after the EofChar character is received. 
CE_RXPARITY The hardware detects a parity error. 
CE_TXFULL The transmit queue is full while trying to queue a character. 
GetCommEventMask 
Syntax WORD GetCommEventMask(nCid, nEvtMask) 


This function retrieves the value of the current event mask, and then clears the mask. This 
function must be used to prevent loss of an event. 


Parameter  Type/Description 
nCid int Specifies the communication device to be examined. The 
OpenComm function returns this value. 
nEvtMask int Specifies which events are to be enabled. For a list of the 
event values, see the SetCommEventMask function, later in 
this chapter. 
Return Value The return value specifies the current event-mask value. Each bit in the event mask speci- 


fies whether a given event has occurred. A bit is set to 1 if the event has occurred. 


GetCommState 
Syntax int GetCommState(nCid, lpDCB) 


This function fills the buffer pointed to by the pDCB parameter with the device control 
block of the communication device specified by the nCid parameter. 
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Return Value 


Parameter Type/Description 


nCid int Specifies the device to be examined. The OpenComm function 
returns this value. 


IpDCB DCB FAR * Points to the DCB data structure that is to receive the 
current device control block. The structure defines the control setting 
for the device. 


The return value specifies the outcome of the function. It is zero if the function was 
successful. If an error occurred, the return value is negative. 


GetCurrentPDB 


Syntax 


Return Value 


WORD GetCurrentPDB() 


This function returns the paragraph address or selector of the current DOS Program Data 
Base (PDB), also known as the Program Segment Prefix (PSP). 


This function has no parameters. 


The return value is the paragraph address or selector of the current PDB. 


GetCurrentPosition 


Syntax 


Return Value 


DWORD GetCurrentPosition(iDC) 


This function retrieves the logical coordinates of the current position. 


Parameter Type/Description 


hDC HDC Identifies a device context. 


The return value specifies the current position. The y-coordinate is in the high-order word; 
the x-coordinate is in the low-order word. 
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GetCurrentTask 
Syntax HANDLE GetCurrentTask( ) 


This function returns the handle of the currently executing task. 


This function has no parameters. 


Return Value The return value identifies the task if the function is successful. Otherwise, it is NULL. 


GetCurrentTime 
Syntax DWORD GetCurrentTime( ) 


This function retrieves the current Windows time. Windows time is the number of millisec- 
onds that have elapsed since the system was booted. 


This function has no parameters. 
Return Value The return value specifies the current time (in milliseconds). 


Comments The GetCurrentTime and GetMessageTime functions return different times. GetMes- 
| sageTime returns the Windows time when the given message was created, not the current 
Windows time. 


The system timer eventually overflows and resets to zero. 


GetCursorPos 
Syntax void GetCursorPos(/pPoint) 


This function retrieves the cursor’s current position (in screen coordinates), that copies 
them to the POINT structure pointed to by the /pPoint parameter. 


Parameter Type/Description 


IpPoint LPPOINT Points to the POINT structure that is to receive the 
screen coordinates of the cursor. 


Return Value None 
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Comments The cursor position is always given in screen coordinates and is not affected by the map- 
ping mode of the window that contains the cursor. 


GetDC 
Syntax HDC GetDC(AWnd) 


This function retrieves a handle to a display context for the client area of the given 
window. The display context can be used in subsequent GDI functions to draw in the client 
area. 


The GetDC function retrieves a common, class, or private display context depending on 
the class style specified for the given window. For common display contexts, GetDC as- 
signs default attributes to the context each time it is retrieved. For class and private 
contexts, GetDC leaves the previously assigned attributes unchanged. 


Parameter Type/Description 


hWnd HWND Identifies the window whose display context is to be re- 
trieved. 


Return Value The return value identifies the display context for the given window’s client area if the 
function is successful. Otherwise, it is NULL. 


Comments After painting with a common display context, the ReleaseDC function must be called to 
release the context. Class and private display contexts do not have to be released. Since 
only five common display contexts are available at any given time, failure to release a dis- 
play context can prevent other applications from accessing a display context. 


GetDCOrg 
Syntax DWORD GetDCOrg(hDC) 


This function obtains the final translation origin for the device context. The final transla- 
tion origin specifies the offset used by Windows to translate device coordinates into client 
coordinates for points in an application’s window. The final translation origin is relative to 
the physical origin of the screen display. 
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Parameter Type/Description 
hDC HDC Identifies the device context whose origin is to be retrieved. 
Return Value The return value specifies the final translation origin (in device coordinates). The y-coordi- 


nate is in the high-order word; the x-coordinate is in the low-order word. 


GetDesktopWindow 
Syntax HWND = GetDesktopWindow( ) 


This function returns the window handle to the Windows desktop window. The desktop 
window covers the entire screen and is the area on top of which all icons and other 
windows are painted. 


This function has no parameters. 


Return Value The return value identifies the Windows desktop window. 
GetDeviceCaps 
Syntax int GetDeviceCaps(hDC, nIndex) 


This function retrieves device-specific information about a given display device. The n/n- 
dex parameter specifies the type of information desired. 


Parameter Type/Description | 
hDC HDC Identifies the device context. 
nIndex int Specifies the item to return. It can be any one of the values 


given in Table 4.9, “GDI Information Indexes.” 


Return Value The return value specifies the value of the desired item. 
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Comments 


GetDeviceCaps 


Table 4.9 lists the values for the n/ndex parameter: 


Table 4.9 GDI Information Indexes 

Index Meaning 

DRIVERVERSION _ Version number; for example, 0x100 for 1.0. 

TECHNOLOGY Device technology. It can be any one of the following values: 
Value Meaning 
DT_PLOTTER Vector plotter 
DT_RASDISPLAY Raster display 
DT_RASPRINTER Raster printer 
DT_RASCAMERA Raster camera 
DT_CHARSTREAM Character stream 
DT_METAFILE Metafile 
DT_DISPFILE Display file 

HORZSIZE Width of the physical display (in millimeters). 

VERTSIZE Height of the physical display (in millimeters). 

HORZRES Width of the display (in pixels). 

VERTRES Height of the display (in raster lines). 

LOGPIXELSX Number of pixels per logical inch along the display width. 

LOGPIXELSY Number of pixels per logical inch along the display height. 

BITSPIXEL Number of adjacent color bits for each pixel. 

PLANES Number of color planes. 

NUMBRUSHES Number of device-specific brushes. 

NUMPENS Number of device-specific pens. 

NUMFONTS Number of device-specific fonts. 

NUMCOLORS Number of entries in the device’s color table. 

ASPECTX Relative width of a device pixel as used for line drawing. 

ASPECTY Relative height of a device pixel as used for line drawing. 

ASPECTXY Diagonal width of the device pixel as used for line drawing. 

PDEVICESIZE Size of the PDEVICE internal data structure. 

CLIPCAPS Flag that indicates the clipping capabilities of the device. It is 1 if the 
device can clip to a rectangle, 0 if it cannot. 

SIZEPALETTE Number of entries in the system palette. This index is valid only if the 


device driver sets the RC_PALETTE bit in the RASTERCAPS index and 
is available only if the driver version is 3.0 or higher. 
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Table 4.9 


Index 


NUMRESERVED 
COLORRES 


RASTERCAPS 


CURVECAPS 


Meaning 


4-168 


GDI Information Indexes (continued) 


Number of reserved entries in the system palette. This index is valid only 
if the device driver sets the RC_PALETTE bit in the RASTERCAPS 
index and is available only if the driver version is 3.0 or higher. 


Actual color resolution of the device in bits per pixel. This index is valid 
only if the device driver sets the RC_PALETTE bit in the RASTER- 
CAPS index and is available only if the driver version is 3.0 or higher. 


Value that indicates the raster capabilities of the device, as shown in the 


following list: 
Capability 
RC_BANDING 
RC_BITBLT 
RC_BITMAP64 


RC_DI_BITMAP 
RC_DIBTODEV 


RC_FLOODFILL 
RC_GDI20_OUTPUT 


RC_PALETTE 
RC_SCALING 
RC_STRETCHBLT 


RC_STRETCHDIB 


Meaning 
Requires banding support. 
Capable of transferring bitmaps. 


Capable of supporting bitmaps larger than 
64K. 


Capable of supporting SetDIBits and 
GetDIBits. 


Capable of supporting the SetDI- 
BitsToDevice function. 


Capable of performing flood fills. 


Capable of supporting Windows version 
2.0 features. . 


Palette-based device. 
Capable of scaling. 


Capable of performing the StretchBIt func- 
tion. 


Capable of performing the StretchDIBits 
function. 


A bitmask that indicates the curve capabilities of the device. The bits 


have the following meanings: 


Bit 


0 


Nn FF WN 


Meaning 

Device can do circles. 
Device can do pie wedges. 
Device can do chord arcs. 
Device can do ellipses. 
Device can do wide borders. 
Device can do styled borders. 


Device can do borders that are wide and 
styled. 
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Table 4.9 GDI Information Indexes (continued) 


Index 


LINECAPS 


POLYGONAL- 
CAPS 


TEXTCAPS 


Meaning 


7 Device can do interiors. 
The high byte is 0. 


A bitmask that indicates the line capabilities of the device. The bits have 
the following meanings: 


Bit Meaning 

0 Reserved. 

l Device can do polyline. 

2 Reserved. 

3 Reserved. 

4 Device can do wide lines. 

a Device can do styled lines. 

6 Device can do lines that are wide and 
styled. 

7 Device can do interiors. 


The high byte is 0. 


A bitmask that indicates the polygonal capabilities of the device. The bits 
have the following meanings: 


Bit Meaning 

0 Device can do alternate fill polygon. 

1 Device can do rectangle. 

Z Device can do winding number fill poly- 
gon. 

3 Device can do scanline. 

4 Device can do wide borders. 

5 Device can do styled borders. 

6 Device can do borders that are wide and 
styled. 

7 Device can do interiors. 


The high byte is 0. 


A bitmask that indicates the text capabilities of the device. The bits have 
the following meanings: 


Bit Meaning 

0 Device can do character output precision. 
1 Device can do stroke output precision. 

2 Device can do stroke clip precision. 
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Table 4.9 | GDI Information Indexes (continued) 


Index Meaning 

3 Device can do 90-degree character rotation. 
Device can do any character rotation. 

5 Device can do scaling independent of X 
and Y. 

6 Device can do doubled character for scal- 
ing. 
Device can do integer multiples for scaling. 
Device can do any multiples for exact scal- 
ing. 

9 Device can do double-weight characters. 

10 Device can do italicizing. 

11 Device can do underlining. 

12 Device can do strikeouts. 

13 Device can do raster fonts. 

14 Device can do vector fonts. 

15 Reserved. Must be retumed zero. 


For a list of all the available abilities, see the LOGFONT data structure in Chapter 7, 
“Data Types and Structures,” in Reference, Volume 2. 


GetDialogBaseUnits 


Syntax 


Return Value 


LONG - GetDialogBaseUnits( ) 


This function returns the dialog base units used by Windows when creating dialog boxes. 
An application should use these values to calculate the average width of characters in the 
system font. 


This function has no parameters. 


The return value specifies the dialog base units. The high-order word contains the height in 
pixels of the current dialog base height unit derived from the height of the system font, and 
the low-order word contains the width in pixels of the current dialog base width unit 
derived from the width of the system font. 
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GetDIBits 


Comments 


The values returned represent dialog base units before being scaled to actual dialog units. 
The actual dialog unit in the x direction is 14 of the width returned by GetDialog- 
BaseUnits. The actual dialog unit in the y direction is 4 of the height returned by the func- 
tion. 


To determine the actual height and width in pixels of a control, given the height (x) and 
width (y) in dialog units and the return value (IDlgBaseUnits) from calling GetDialog- 
BaseUnits, use the following formula: 


(x * LOWORD(1D1gBaseUnits))/4 
(y * HIWORD(1D1gBaseUnits))/8 


To avoid rounding problems, perform the multiplication before the division in case the 
dialog base units are not evenly divisible by four. 


GetDIBits 


Syntax 


int GetDIBits(ADC, hBitmap, nStartScan, nNumScans, IpBits, lpBitsInfo, wUsage) 


This function retrieves the bits of the specified bitmap and copies them, in device-inde- 
pendent format, into the buffer that is pointed to by the /pBits parameter. The IpBitsInfo 
parameter retrieves the color format for the device-independent bits. 


Parameter Type/Description 

hDC HDC Identifies the device context. 

ABitmap HBITMAP Identifies the bitmap. 

nStartScan WORD _ Specifies the first scan line in the destination bitmap to 
set in /pBits. 

nNumScans WORD _ Specifies the number of lines to be copied. 

IpBits LPSTR Points to a buffer that will receive the bitmap bits in 
device-independent format. 

IpBitsInfo LPBITMAPINFO Points toa BITMAPINFO data structure 
that specifies the color format and dimension for the device-inde- 
pendent bitmap. 

wUsage WORD _ Specifies whether the bmiColors[ ] fields of the /pBits- 


Info parameter are to contain explicit RGB values or indexes into 
the currently realized logical palette. The wUsage parameter must 
be one of the following values: 


SAGER 
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Return Value 


Comments 


Parameter Type/Description 
Value . Meaning 
DIB_PAL_COLORS The color table is to consist of an 
: array of 16-bit indexes into the cur- 
rently realized logical palette. 
DIB_RGB_COLORS The color table is to contain literal 


RGB values. 


The return value specifies the number of scan lines copied from the bitmap. It is zero if 
there was an error. 


If the /pBits parameter is NULL, GetDIBits fills in the BITMAPINFO data structure to 
which the /pBitsInfo parameter points, but does not retrieve bits from the bitmap. 


The bitmap identified by the hBitmap parameter must not be selected into a device context 
when the application calls this function. 


The origin for device-independent bitmaps is the bottom-left corner of the bitmap, not the 
top-left corner, which is the origin when the mapping mode is MM_TEXT. 


This function also retrieves a bitmap specification formatted for Microsoft OS/2 Presenta- 
tion Manager versions 1.1 and 1.2 if the /pBitsInfo parameter points to a BITMAPCORE- 
INFO data structure. 


GetDigCtriID 


Syntax 


Return Value 


Comments 


int GetDigCtrIID(AWnd) 


This function returns the ID value of the child window identified by the hWnd parameter. 


Parameter Type/Description 


hWnd HWND Identifies the child window. 


The return value is the numeric identifier of the child window if the function is successful. 
If the function fails, or if hWnd is not a valid window handle, the return value is NULL. 


Since top-level windows do not have an ID value, the return value of this function is in- 
valid if the hWnd parameter identifies a top-level window. 
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GetDigltem 


GetDigltem 
Syntax 


Return Value 


Comments 


GetDigltemint 
Syntax 


HWND_  GetDigItem(/D/g, nIDDIglitem) 


This function retrieves the handle of a control contained in the dialog box specified by the 
hDlg parameter. 


Parameter Type/Description 
hDlg HWND Identifies the dialog box that contains the control. 
nIDDIglItem int Specifies the integer ID of the item to be retrieved. 


The return value identifies the given control. It is NULL if no control with the integer ID 
given by the nJDD/gItem parameter exists. 


The GetDlgItem function can be used with any parent-child window pair, not just dialog 
boxes. As long as the hD/g parameter specifies a parent window and the child window has 
a unique ID (as specified by the hMenu parameter in the CreateWindow function that 
created the child window), GetDlgItem returns a valid handle to the child window. 


WORD GetDigItemInt(AD/lg, nJDDIglItem, lpTranslated, bSigned) 


This function translates the text of a control in the given dialog box into an integer value. 
The GetDlgItemInt function retrieves the text of the control identified by the nJDDlgItem 
parameter. It translates the text by stripping any extra spaces at the beginning of the text 
and converting decimal digits, stopping the translation when it reaches the end of the text 
or encounters any nonnumeric character. If the bSigned parameter is nonzero, Get- 
DigItemInt checks for a minus sign (—) at the beginning of the text and translates the text 
into a signed number. Otherwise, it creates an unsigned value. 


GetDlgItemInt returns zero if the translated number is greater than 32,767 (for signed 
numbers) or 65,535 (for unsigned). When errors occur, such as encountering nonnumeric 
characters and exceeding the given maximum, GetDlgItemInt copies zero to the location 
pointed to by the /pTranslated parameter. If there are no errors, /pTranslated receives a 
nonzero value. If IpTranslated is NULL, GetDlgItemInt does not warn about errors. Get- 
DigItemInt sends a WM_GETTEXT message to the control. 
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Parameter Type/Description 

hDlg HWND Identifies the dialog box. 

nIDDIgltem int Specifies the integer identifier of the dialog-box item to be 
translated. 

IpTranslated BOOL FAR * Points to the Boolean variable that is to receive the 
translated flag. 

_bSigned BOOL _ Specifies whether the value to be retrieved is signed. 
Return Value The return value specifies the translated value of the dialog-box item text. Since zero is a 


valid return value, the /pTranslated parameter must be used to detect errors. If a signed re- 
turn value is desired, it should be cast as an int type. 


GetDigitemText 
Syntax int GetDigItemText(iD/g, nIDDIigltem, IpString, nMaxCount) 


This function retrieves the caption or text associated with a control in a dialog box. The 
GetDlgItemText function copies the text to the location pointed to by the /pString parame- 
ter and returns a-count of the number of characters it copies. 


GetDlgItemText sends a WM_GETTEXT message to the control. 


Parameter Type/Description 

hDlg HWND Identifies the dialog box that contains the control. 

nlDDlgltem int Specifies the integer identifier of the dialog-box item whose 
caption or text is to be retrieved. 

IpString LPSTR Points to the buffer to receive the text. 

nMaxCount int Specifies the maximum length (in bytes) of the string to be 
copied to /pString. If the string is longer than nMaxCount, it is trun- 
cated. 

Return Value The return value specifies the actual number of characters copied to the buffer. It is zero if 


no text is copied. 
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GetDOSEnvironment 
Syntax LPSTR GetDOSEnvironment( ) 


This function returns a far pointer to the environment string of the currently running task. 
See Microsoft MS-DOS Programmer’s Reference for more information on the format and 
contents of the environment string. 


This function has no parameters. 


Comments Unlike an application, a dynamic-link library (DLL) does not have a copy of the environ- 
_ ment string. As a result, a library must call this function to retrieve the environment string. 


GetDoubleClickTime 
Syntax WORD GetDoubleClickTime( ) 


This function retrieves the current double-click time for the mouse. A double-click is a ser- 
ies of two clicks of the mouse button, the second occurring within a specified time after 
the first. The double-click time is the maximum number of milliseconds that may occur be- 
tween the first and second click of a double-click. 


This function has no parameters. 


Return Value The return value specifies the current double-click time (in milliseconds). 


GetDriveType 
Syntax WORD GetDriveType(nDrive) 


This function determines whether a disk drive is removeable, fixed, or remote. 


Parameter Type/Description 


nDrive int Specifies the drive for which the type is to be determined. 
Drive A: is 0, drive B: is 1, drive C: is 2, and so on. 
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Return Value 


The return value specifies the type of drive. It can be one of the following values: 


Value | Meaning 


DRIVE_REMOVEABLE Disk can be removed from the drive. 
DRIVE_FIXED Disk cannot be removed from the drive. 
DRIVE_REMOTE Drive is a remote (network) drive. 


The return value is zero if the function cannot determine the drive type, or 1 if the 
specified drive does not exist. 


GetEnvironment 


Syntax 


Return Value 


int GetEnvironment(/pPortName, lpEnviron, nMaxCount) 


This function retrieves the current environment that is associated with the device attached 
to the system port specified by the JpPortName parameter, and copies it into the buffer 
specified by the /pEnviron parameter. The environment, maintained by GDI, contains bi- 
nary data used by GDI whenever a device context is created for the device on the given 
port. 


The function fails if there is no environment for the given port. 


An application can call this function with the /pEnviron parameter set to NULL to deter- 
mine the size of the buffer required to hold the environment. It can then allocate the buffer 
and call GetEnvironment a second time to retrieve the environment. 


Parameter Type/Description 
IpPortName LPSTR Points to the null-terminated character string that specifies 
the name of the desired port. 
IpEnviron LPSTR Points to the buffer that will receive the environment. 
nMaxCount . oe Specifies the maximum number of bytes to copy to the 
uffer. 


The return value specifies the number of bytes copied to /pEnviron. If IpEnviron is NULL, 
the return value is the size in bytes of the buffer required to hold the environment. It is zero 
if the environment cannot be found. 
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Comments The first field in the buffer pointed to by JpEnviron must be the same as that passed in the 
IpDeviceName parameter of the CreateDC function. If JpPortName specifies a null port 
(as defined in the WIN.INI file), the device name pointed to by /pEnviron is used to locate 
the desired environment. 


GetFocus 

Syntax HWND ~ GetFocus( ) 
This function retrieves the handle of the window that currently owns the input focus. 
This function has no parameters. . 

Return Value The return value identifies the window that currently owns the focus if the function is 


successful. Otherwise, it is NULL. 


GetFreeSpace 


Syntax DWORD  GetFreeSpace(wFlags) 
This function scans the global heap and returns the number of bytes of memory currently 
available. 
Parameter Type/Description 
wFlags WORD _ Specifies whether to scan the heap above or below the 
EMS bank line in large-frame and small-frame EMS systems. If it is 
set to GMEM_NOT_BANKED, GetFreeSpace returns the amount 
of memory available below the line. If wFlags is zero, Get- 
FreeSpace returns the amount is the memory available above the 
EMS bank line. The wF lags parameter is ignored for non-EMS sys- 
tems. 
Return Value The return value is the amount of available memory in bytes. This memory is not neces- 


sarily contiguous; the GlobalCompact function returns the number of bytes in the largest 
block of free global memory. 


-GetGValue 
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GetGValue 
Syntax 


Return Value 


Comments 


GetinputState 
Syntax 


Return Value 


BYTE GetGValue(rgbColor) 


This macro extracts the green value from an RGB color value. 


Parameter Type/Description 


rgbColor DWORD Specifies a red, a green, and a blue color field, each 
specifying the intensity of the given color. 


The return value specifies a byte that contains the green value of the rgbColor parameter. 


The value OFFH corresponds to the maximum intensity value for a single byte; OOOH corre- 
sponds to the minimum intensity value for a single byte. 


BOOL  GetInputState() 


This function determines whether there are mouse, keyboard, or timer events in the system 
queue that require processing. An event is a record that describes interrupt-level input. 
Mouse events occur when a user moves the mouse or clicks a mouse button. Keyboard 
events occur when a user presses one or more keys. Timer events occur after a specified 
number of clock ticks. The system queue is the location in which Windows stores mouse, 
keyboard, and timer events. 


This function has no parameters. 


The return value specifies whether mouse, keyboard or timer input occurs. It is nonzero if 
input is detected. Otherwise, it is zero. 


GetinstanceData 


Syntax 


int GetInstanceData(hinstance, pData, nCount) 


This function copies data from a previous instance of an application into the data area of 
the current instance. The /nstance parameter specifies which instance to copy data from, 
pData specifies where to copy the data, and nCount specifies the number of bytes to copy. 
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Parameter Type/Description 
hInstance HANDLE Identifies a previous call of the application. 
pData NPSTR Points to a buffer in the current instance. 
nCount int Specifies the number of bytes to copy. 

Return Value The return value specifies the number of bytes actually copied. 


GetKBCodePage 
Syntax int GetKBCodePage( ) 
This function determines which OEM/ANSI tables are loaded by Windows. 


This function has no parameters. 


Return Value The return value specifies the code page currently loaded by Windows. It can be one of the 
following values: 


Value Meaning 

437 Default (USA, used by most countries: indicates that there is no 
OEMANSL.BIN in the Windows directory) 

850 - International (QEMANSI.BIN = XLAT850.BIN) 

860 Portugal (OQEMANSI.BIN = XLAT860.BIN) 

861 Iceland (QEMANSLBIN = XLAT861.BIN) 

863 French Canadian (OEMANSI.BIN = XLAT863.BIN) 

865 Norway/Denmark (OQEMANSI.BIN = XLAT865.BIN) 

Comments If the file OEMANSI.BIN is in the Windows directory, Windows reads it and overwrites 


the OEM/ANSI translation tables in the keyboard driver. 
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When the user selects a language within the Setup program and the language does not use 
the default code page (437), Setup copies the appropriate file (such as XLATPO.BIN) to 
OEMANSL.BIN in the Windows system directory. If the language uses the default code 
page, Setup deletes OEMANSI.BIN, if it exists, from the Windows system directory. 


GetKeyboardState 


Syntax 


Return Value 


Comments 


void GetKeyboardState(/pKeyState) 


This function copies the status of the 256 virtual-keyboard keys to the buffer specified by 
the IpKeyState parameter. The high bit of each byte is set to 1 if the key is down, or it is set 
to 0 if it is up. The low bit is set to 1 if the key was pressed an odd number of times since 


_ Startup. Otherwise, it is set to 0. 


Parameter Type/Description 
IpKeyState BYTE FAR * Points to the 256-byte buffer of virtual-key codes. 
None. 


An application calls the GetKeyboardState function in response to a keyboard-input 
message. This function retrieves the state of the keyboard when the input message was 
generated. 


To obtain state information for individual keys, follow these steps: 


1. Create an array of characters that is 265 bytes long. 
2. Copy the contents of the buffer pointed to by the /p>KeyState parameter into the array. 


3. Use the virtual-key code from Appendix A, “Virtual-Key Codes,” in Reference, Volume 
2, to obtain an individual key state. 
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GetKeyboardType 
Syntax int GetKeyboardType(nTypeFlag) 


This function retrieves the system-keyboard type. 


Parameter Type/Description 
nTypeF lag int Determines whether the function returns a value indicating 
the type or subtype of the keyboard. It may be one of the following 
values: 
Value Meaning 
0 Function returns the keyboard type. 
1 Function returns the keyboard subtype. 
2 Function returns the number of function keys on the 
keyboard. 
Return Value The return value indicates the type or subtype of the system keyboard or the number of 


function keys on the keyboard. The subtype is an OEM-dependent value. The type may be 
one of the following values: 


1 IBM® PC/XT™, or compatible (83-key) keyboard 
Olivetti® M24 “ICO” (102-key) keyboard 

IBM AT® (84-key) or similar keyboard 

IBM Enhanced (101- or 102-key) keyboard 

Nokia 1050 and similar keyboards 


nH A F&F W DN 


Nokia 9140 and similar keyboards 


The return value is zero if the nTypeF lag parameter is greater than 2 or if the function fails. 


GetKeyNameText 
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Comments 


An application can determine the number of function keys on a keyboard from the key- 
board type. The following shows the number of function keys for each keyboard type: 


Type 
1 


2 
3 
4 
5 
6 


GetKeyNameText 


Syntax 


Return Value 


Number of Function Keys 
10 

12 (sometimes 18) 

10 | 

12 

10 

24 


int GetKeyNameText(/Param, lpBuffer, nSize) 


This function retrieves a string which contains the name of a key. 


The keyboard driver maintains a list of names in the form of character strings for keys with 
names longer than a single character. The key name is translated according to the layout of 
the currently installed keyboard. The translation is performed for the principal language 
supported by the keyboard driver. 


Parameter 


lParam 


lpBuffer 


nSize 


Type/Description 


DWORD Specifies the 32-bit parameter of the keyboard message 
(such as WM_KEYDOWN) which the function is processing. Byte 3 
(bits 16-23) of the long parameter is a scan code. Bit 20 is the ex- 
tended bit that distinguishes some keys on an enhanced keyboard. Bit 
21 is a “don’t care” bit; the application calling this function sets this 
bit to indicate that the function should not distinguish between left 
and right control and shift keys, for example. 


LPSTR Specifies a buffer to receive the key name. 


WORD _ Specifies the maximum length in bytes of the key name, 
not including the terminating NULL character. 


The return value is the actual length of the string copied to /pBuffer. 


4-183 7 GetKeyState 


GetKeyState 
Syntax int GetKeyState(nVirtKey) 


This function retrieves the state of the virtual key specified by the nVirtKey parameter. The 
state specifies whether the key is up, down, or toggled. 


Parameter Type/Description 


nVirtKey int Specifies a virtual key. If the desired virtual key is a letter or 
digit (A through Z, a through z, or 0 through 9), nVirtKey must be set 
to the ASCII value of that character. For other keys, it must be one of 
the values listed in Appendix A, “Virtual-Key Codes,” in Reference, 
Volume 2. 


Return Value The return value specifies the state of the given virtual key. If the high-order bit is 1, the 
key is down. Otherwise, it is up. If the low-order bit is 1, the key is toggled. A toggle key, 
such as the CAPSLOCK key, is toggled if it has been pressed an odd number of times since 
the system was started. The key is untoggled if the low bit is 0. 


Comments An application calls the GetKeyState function in response to a keyboard-input message. 
This function retrieves the state of the key when the input message was generated. 


GetLastActivePopup 
Syntax HWND = GetLastActivePopup(iwndOwner) 


This function determines which pop-up window owned by the window identified by the 
hwndOwner parameter was most recently active. 


Parameter Type/Description 
hwndOwner HWND Identifies the owner window. 
Return Value The return value identifies the most-recently active pop-up window. The return value will 


be hwndOwner if any of the following conditions are met: 


« The window identified by hwndOwner itself was most recently active. 
= The window identified by hwndOwner does not own any pop-up windows. 


= The window identified by hwndOwner is not a top-level window or is owned by 
another window. 
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GetMapMode 
Syntax 


Return Value 


GetMenu 
Syntax 


Return Value 


int GetMapMode(hDC) 


This function retrieves the current mapping mode. See the SetMapMode function, later in 
this chapter, for a description of the mapping modes. 


Parameter Type/Description 


hDC HDC Identifies the device context. 


The return value specifies the mapping mode. 


HMENU- GetMenu(hWna) 


This function retrieves a handle to the menu of the specified window. 


Parameter Type/Description 


hWnd HWND Identifies the window whose menu is to be examined. 


The return value identifies the menu. It is NULL if the given window has no menu. The re- 
turn value is undefined if the window is a child window. 


GetMenuCheckMarkDimensions 


Syntax 


Return Value 


DWORD GetMenuCheckMarkDimensions( ) 


This function returns the dimensions of the default checkmark bitmap. Windows displays 
this bitmap next to checked menu items. Before calling the SetMenuItemBitmaps func- 
tion to replace the default checkmark, an application should call the GetMenuCheck- 
MarkDimensions function to determine the correct size for the bitmaps. 


This function has no parameters. 


The return value specifies the height and width of the default checkmark bitmap. The high- 
order word contains the height in pixels and the low-order word contains the width. 
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GetMenultemCount 


Syntax WORD  GetMenultemCount(iMenu) 


) ( 4 


This function determines the number of items in the menu identified by the hAMenu parame- 
ter. This may be either a pop-up or a top-level menu. 


| 


Parameter Type/Description 
hMenu HMENU Identifies the handle to the menu to be examined. 
Return Value The return value specifies the number of items in the menu specified by the hMenu para- 


meter if the function is successful. Otherwise, it is —1. 


GetMenultemID 
Syntax WORD GetMenultemID(iMenu, nPos) 


This function obtains the menu-item identifier for a menu item located at the position de- 
fined by the nPos parameter. 


Parameter Type/Description 


hMenu HMENU Identifies a handle to the pop-up menu that contains the 
item whose ID is being retrieved. 


nPos int Specifies the position (zero-based) of the menu item whose ID 
is being retrieved. 


Return Value The return value specifies the item ID for the specified item in a pop-up menu if the func- 
tion is successful; if hMenu is NULL or if the specified item is a pop-up menu (as opposed 
to an item within the pop-up menu), the return value is —1. 


GetMenuState 
Syntax WORD GetMenuState(hMenu, wid, wFlags) 


This function obtains the number of items in the pop-up menu associated with the menu 
item specified by the w/d parameter if the hMenu parameter identifies a menu with an as- 
sociated pop-up menu. If AMenu identifies a pop-up menu, this function obtains the status 
of the menu item associated with wid. 


GetMenuState 


Return Value 
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Parameter Type/Description 
hMenu HMENU Identifies the menu. 
wld WORD _Specifies the menu-item ID. 
wF lags WORD Specifies the nature of the w/d parameter. If the wFlags 


parameter contains MF_BYPOSITION, wid specifies a (zero-based) 
relative position; if wFlags contains MF_BYCOMMAND, wild speci- 
fies the item ID. 


The return value specifies the outcome of the function. It is —1 if the specified item does 
not exist. If the menu itself does not exist, a fatal exit occurs. If wid identifies a pop-up 


‘menu, the return value contains the number of items in the pop-up menu in its high-order 


byte, and the menu flags associated with the pop-up menu in its low-order byte; otherwise, 
it is a mask (Boolean OR) of the values from the following list (this mask describes the sta- 
tus of the menu item that w/d identifies): 


Value 
MF_CHECKED 
MF_DISABLED 
MF_ENABLED 
MF_GRAYED 
MF_MENUBARBREAK 


MF_MENUBREAK 


MF_SEPARATOR 


MF_UNCHECKED 


Meaning 

Checkmark is placed next to item (pop-up menus only). 
Item is disabled. 

Item is enabled. 

Item is disabled and grayed. 


Same as MF_MENUBREAK, except for pop-up menus 
where the new column is separated from the old column 
by a vertical dividing line. 


Item is placed on a new line (static menus) or in a new 
column (pop-up menus) without separating columns. 


Horizontal dividing line is drawn (pop-up menus only). 
This line cannot be enabled, checked, grayed, or 
highlighted. The JpNew/tem and wIDNewlItem parame- 
ters are ignored. 


Checkmark is not placed next to item (default). 
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GetMenuString 
Syntax int GetMenuString(iMenu, wIDItem, IpString, nMaxCount, wFlag) 
This function copies the label of the specified menu item into the /pString parameter. 
Parameter Type/Description 
hMenu HMENU Identifies the menu. 
wlDItem WORD _ Specifies the integer identifier of the menu item (from the 
resource file) or the offset of the menu item in the menu, depending 
on the value of the wF/ag parameter. 
IpString LPSTR Points to the buffer that is to receive the label. 
nMaxCount int Specifies the maximum length of the label to be copied. If the 
label is longer than the maximum specified in nMaxCount, the extra 
characters are truncated. 
wFlag WORD _Specifies the nature of the w/D parameter. If wFlags con- 
tains MF_BYPOSITION, wid specifies a (zero-based) relative 
position; if the wFlags parameter contains MF_BYCOMMAND, wid 
specifies the item ID. 
Return Value The return value specifies the actual number of bytes copied to the buffer. 
Comments The nMaxCount parameter should be one larger than the number of characters in the label 


to accommodate the null character that terminates a string. 
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GetMessage 
Syntax BOOL GetMessage(/pMsg, hWnd, wMsgFilterMin, wMsgF ilterMax) 


This function retrieves a message from the application queue and places the message in the 
data structure pointed to by the /pMsg parameter. If no message is available, the GetMes- 
sage function yields control to other applications until a message becomes available. 


GetMessage retrieves only messages associated with the window specified by the hWnd 
parameter and within the range of message values given by the wMsgFilterMin and 
wMsgFilterMax parameters. If hWnd is NULL, GetMessage retrieves messages for any 
window that belongs to the application making the call. (The GetMessage function does 
not retrieve messages for windows that belong to other applications.) If wMsgFilterMin 
and wMsgFilterMax are both zero, GetMessage returns all available messages (no filtering 
is performed). 


| The constants WM_KEYFIRST and WM_KEYLAST can be used as filter values to re- 
trieve all messages related to keyboard input; the constants WM_MOUSEFIRST and 
WM_MOUSELAST can be used to retrieve all mouse-related messages. 


Parameter Type/Description 
/ 


IpMsg LPMSG Points to an MSG data structure that contains 
message information from the Windows application queue. 


hWnd HWND Identifies the window whose messages are to be ex- 
amined. If hWnd is NULL, GetMessage retrieves messages for 
any window that belongs to the application making the call. 


wMsgF ilterMin WORD Specifies the integer value of the lowest message 
value to be retrieved. 


wMsgFilterMax WORD Specifies the integer value of the highest message 
value to be retrieved. 


Return Value The return value specifies the outcome of the function. It is nonzero if a message other 
than WM_QUIT is retrieved. It is zero if the WM_QUIT message is retrieved. 


The return value is usually used to decide whether to terminate the application’s main loop 
and exit the program. 


Comments — In addition to yielding control to other applications when no messages are available, the 
GetMessage and PeekMessage functions also yield control when WM_PAINT or 
WM_TIMER messages for other tasks are available. 


The GetMessage, PeekMessage, and WaitMessage functions are the only ways to let 
other applications run. If your application does not call any of these functions for long peri- 
ods of time, other applications cannot run. 
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GetMessagePos 


When GetMessage, PeekMessage, and WaitMessage yield control to other applications, 
the stack and data segments of the application calling the function may move in memory to 
accommodate the changing memory requirements of other applications. If the application 
has stored long pointers to objects in the data or stack segment (that is, global or local vari- 
ables), these pointers can become invalid after a call to GetMessage, PeekMessage, or 
WaitMessage. The /pMsg parameter of the called function remains valid in any case. 


GetMessagePos 


Syntax 


Return Value 


DWORD_  GetMessagePos( ) 


This function returns a long value that represents the cursor position (in screen coordi- 
nates) when the last message obtained by the GetMessage function occurred. 


This function has no parameters. 


The return value specifies the x- and y-coordinates of the cursor position. The x-coordinate 
is in the low-order word, and the y-coordinate is in the high-order word. If the return value 
is assigned to a variable, the MAKEPOINT macro can be used to obtain a POINT struc- 
ture from the return value; the LOWORD or HIWORD macro can be used to extract the 
x- or the y-coordinate. 


Comments To obtain the current position of the cursor instead of the position when the last message 
occurred, use the GetCursorPos function. 

GetMessageTime 

Syntax DWORD  GetMessageTime( ) 


Return Value 


Comments 


This function returns the message time for the last message retrieved by the GetMessage 
function. The time is a long integer that specifies the elapsed time (in milliseconds) from 
the time the system was booted to the time the message was created (placed in the applica- 
tion queue). 


This function has no parameters. 
The return value specifies the message time. 


Do not assume that the return value is always increasing. The return value will “wrap 
around” to zero if the timer count exceeds the maximum value for long integers. 


To calculate time delays between messages, subtract the time of the second message from 
the time of the first message. 
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GetMetaFile 
Syntax 


Return Value 


HANDLE  GetMetaFile(/pFilename) 


This function creates a handle for the metafile named by the /pFilename parameter. 


Parameter Type/Description 


IpFilename LPSTR Points to the null-terminated character string that specifies 
the DOS filename of the metafile. The metafile is assumed to exist. 


The return value identifies a metafile if the function is successful. Otherwise, it is NULL. 


GetMetaFileBits 


Syntax 


Return Value 


Comments 


HANDLE GetMetaFileBits(iMF) 


This function returns a handle to a global memory block that contains the specified meta- 
file as a collection of bits. The memory block can be used to determine the size of the meta- 
file or to save the metafile as a file. The memory block should not be modified. 


Parameter Type/Description 


hMF HANDLE Identifies the memory metafile. 


The return value identifies the global memory block that contains the metafile. If an error 
occurs, the return value is NULL. 


The handle used as the hMF parameter becomes invalid when the GetMetaFileBits func- 
tion returns, so the returned global memory handle must be used to refer to the metafile. 


Memory blocks created by this function are unique to the calling application and are not 
shared by other applications. These blocks are automatically deleted when the application 
terminates. 


GetModuleFileName 


Syntax 


int GetModuleFileName(hModule, lpFilename, nSize) 


This function retrieves the full pathname of the executable file from which the specified 
module was loaded. The function copies the null-terminated filename into the buffer 
pointed to by the /pFilename parameter. 
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GetModuleHandle 


Return Value 


Parameter Type/Description 

hModule HANDLE Identifies the module or the instance of the module. 
IpFilename LPSTR Points to the buffer that is to receive the filename. 
nSize int Specifies the maximum number of characters to copy. If the 


filename is longer than the maximum number of characters specified 
by the nSize parameter, it is truncated. 


The return value specifies the actual length of the string copied to the buffer. 


GetModuleHandle 


Syntax 


Return Value 


HANDLE GetModuleHandle(/pModuleName) 


This function retrieves the module handle of the specified module. 


Parameter Type/Description 


IpModuleName LPSTR Points to a null-terminated character string that specifies 
the module. 


The return value identifies the module if the function is successful. Otherwise, it is NULL. 


GetModuleUsage 


Syntax 


Return Value 


int GetModuleUsage(hModule) 


This function returns the reference count of a specified module. 


Parameter Type/Description 


hModule HANDLE Identifies the module or an instance of the module. 


The return value specifies the reference count of the module. 


GetNearestColor 
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GetNearestColor 


Syntax 


Return Value 


DWORD  GetNearestColor(iDC, crColor) 


This function returns the closest logical color to a specified logical color the given device 
can represent. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
crColor COLORREF _ Specifies the color to be matched. 


The return value specifies an RGB color value that names the solid color closest to the 
crColor value that the device can represent. 


GetNearestPaletteIndex 


Syntax 


Return Value 


WORD _ GetNearestPaletteIndex(hPalette, crColor) 


This function returns the index of the entry in a logical palette which most closely matches 
a color value. 


Parameter Type/Description 
hPalette HPALETTE Identifies the logical palette. 
crColor COLORREF _ Specifies the color to be matched. 


The return value is the index of an entry in a logical palette. The entry contains the color 
which most nearly matches the specified color. 


GetNextDigGroupltem 


Syntax 


HWND_ GetNextDlgGroupItem(hD/g, hCtl, bPrevious) 


This function searches for the next (or previous) control within a group of controls in the 
dialog box identified by the hD/g parameter. A group of controls consists of one or more 
controls with WS_GROUP style. 
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GetNexiDigTabltem 


Return Value 


Comments 


Parameter 


hDlig 
hcl 


bPrevious 


Type/Description 
HWND Identifies the dialog box being searched. 


HWND Identifies the control in the dialog box where the search 
Starts. 


BOOL Specifies how the function is to search the group of con- 
trols in the dialog box. If the bPrevious parameter is zero, the 
function searches for the previous control in the group. If bPrevious 
is nonzero, the function searches for the next control in the group. 


The return value identifies the next or previous control in the group. 


If the current item is the last item in the group and bPrevious is zero, the GetNext- 
DigGroupItem function returns the window handle of the first item in the group. If the 
current item is the first item in the group and bPrevious is nonzero, GetNext- 
DigGrouplItem returns the window handle of the last item in the group. 


GetNextDigTabitem 
HWND = GetNextDigTabItem(iD/g, hCtl, bPrevious) 


Syntax 


Return Value 


This function obtains the handle of the first control that has the WS_TABSTOP style that 
precedes (or follows) the control identified by the Ctl parameter. 


Parameter 


hDlg 
hCtl 


bPrevious 


Type/Description 
HWND Identifies the dialog box being searched. 


HWND Identifies the control to be used as a starting point for the 
search. 


BOOL Specifies how the function is to search the dialog box. If 
the bPrevious parameter is zero, the function searches for the pre- 
vious control in the dialog box. If bPrevious is nonzero, the function 
searches for the next control in the dialog box. Identifies the control 
to be used as a Starting point for the search. 


The return value identifies the previous (or next) control that has the WS_TABSTOP style 


set. 


GetNextWindow 4-194 


GetNextWindow 


Syntax 


Return Value 


GetNumTasks 
Syntax 


Reiurn Value 


HWND_ GetNextWindow(hWnd, wFlag) 


This function searches for a handle that identifies the next (or previous) window in the 
window-manager’s list. The window-manager’s list contains entries for all top-level 
windows, their associated child windows, and the child windows of any child windows. If 
the hWnd parameter is a handle to a top-level window, the function searches for the next 
(or previous) handle to a top-level window; if hWnd is a handle to a child window, the 
function searches for a handle to the next (or previous) child window. 


Parameter Type/Description 
hWnd HWND Identifies the current window. 
wFlag WORD _ Specifies whether the function returns a handle to the 


next window or to the previous window. It can be either of the fol- 
lowing values: 


Value Meaning 

GW_HWNDNEXT The function returns a handle to the 
. next window. 

GW_HWNDPREV The function returns a handle to the 


previous window. 


The return value identifies the next (or the previous) window in the window-manager’s list. 


int GetNumTasks( ) 


This function returns the number of tasks currently executing in the system. A task is a 
unique instance of a Windows application. 


This function has no parameters. 


The return value specifies an integer that represents the number of tasks currently execut- 
ing in the system. 
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GetObject 


GetObject 
Syntax 


Return Value 


int GetObject(hObject, nCount, lpObject) 


This function fills a buffer with the logical data that defines the logical object specified by 
the hObject parameter. The GetObject function copies the number of bytes of data 
specified by the nCount parameter to the buffer pointed to by the /pObject parameter. The 
function retrieves data structures of the LOGPEN, LOGBRUSH, LOGFONT, or BIT- 
MAP type, or an integer, depending on the logical object. The buffer must be sufficiently 
large to receive the data. 


If hObject specifies a bitmap, the function returns only the width, height, and color format 
information of the bitmap. The actual bits must be retrieved by using the GetBitmapBits 
function. 


If hObject specifies a logical palette, it retrieves a two-byte value that specifies the number 
of entries in the palette; it does not retrieve the entire LOGPALETTE data structure that 
defines the palette. To get information on palette entries, an application must call the Get- 
PaletteEntries function. 


Parameter Type/Description 

hObject HANDLE Identifies a logical pen, brush, font, bitmap, or 
palette. a 

nCount int Specifies the number of bytes to be copied to the buffer. 


lpObject LPSTR Points to the buffer that is to receive the information. 


The return value specifies the actual number of bytes retrieved. It is zero if an error occurs. 


GetPaletteEntries 


Syntax 


WORD GetPaletteEntries(hPalette, wStartIndex, wNumEntries, lpPaletteEntries) 


This function retrieves a range of palette entries in a logical palette. 
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Parameter Type/Description 

hPalette HPALETTE Identifies the logical palette. 

wStartIndex WORD Specifies the first entry in the logical palette to be re- 
trieved. 

wNumEntries WORD _ Specifies the number of entries in the logical palette 
to be retrieved. . 

IpPaletteEntries LPPALETTEENTRY Points to an array of PALETTE- 


ENTRY data structures to receive the palette entries. The array 
must contain at least as many data structures as specified by the 
wNumEntries parameter. . 


Return Value The return value is the number of entries retrieved from the logical palette. It is zero if the 
function failed. 


“~ GetParent 
Syntax HWND_ GetParent(iWnd) 


This function retrieves the window handle of the specified window’s parent window (if 


any). 
Parameter | Type/Description 
hWnd HWND Identifies the window whose parent window handle is to 
be retrieved. 
Return Value The return value identifies the parent.window. It is NULL if the window has no paren 
window. 
GetPixel 
Syntax DWORD = GetPixel(iDC, X, Y) 


This function retrieves the RGB color value of the pixel at the point specified by the X and 
Y parameters. The point must be in the clipping region. If the point is not in the clipping re- 
gion, the function is ignored. 
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Parameter Type/Description 

hDC HDC Identifies the device context. 

XxX int Specifies the logical x-coordinate of the point to be examined. 

Y int Specifies the logical y-coordinate of the point to be examined. 
Return Value The return value specifies an RGB color value for the color of the given point. It is -1 if 


the coordinates do not specify a point in the clipping region. 


Comments Not all devices support the GetPixel function. For more information, see the RC_BITBLT 
raster capability in the GetDeviceCaps function, earlier in this chapter. 


GetPolyFillMode 
Syntax int GetPolyFillMode(hDC) 


This function retrieves the current polygon-filling mode. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
Return Value The return value specifies the polygon-filling mode. It can be any one of the following 
values: 
Value Meaning 


ALTERNATE _ Alternate mode 
WINDING Winding-number mode 


For a description of these modes, see the SetPolyFillMode function, later in this chapter. 


GetPriorityClipboardFormat 
Syntax int GetPriorityClipboardFormat(/pPriorityList, nCount) 


This function returns the first clipboard format in a list for which data exist in the clip- 
board. 
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Return Value 


Parameter Type/Description 


lpPriorityList WORD FAR * _ Points to an integer array that contains a list of 
clipboard formats in priority order. For a description of the data for- 
mats, see the SetClipboardData function later in this chapter. 


nCount int Specifies the number of entries in /pPriorityList. This value 
must not be greater than the actual number of entries in the list. 


The return value is the highest priority clipboard format in the list for which data exist. If 
no data exist in the clipboard, this function returns NULL. If data exist in the clipboard 
which did not match any format in the list, the return value is —1. 


GetPrivateProfilelnt 


Syntax 


WORD = GetPrivateProfileInt(/pApplicationName, IpKeyName, nDefault, lpFileName) 
This function retrieves the value of an integer key from the specified initialization file. 


The function searches the file for a key that matches the name specified by the pKeyName 
parameter under the application heading specified by the /pApplicationName parameter. 
An integer entry in the initialization file must have the following form: 


Capplication name] 
keyname = value 


Parameter Type/Description 

[pApplicationName LPSTR Points to the name of a Windows application that 
appears in the initialization file. 

IpKeyName LPSTR Points to a key name that appears in the initializa- 
tion file. 

nDefault _ int Specifies the default value for the given key if the key 


cannot be found in the initialization file. 


[pFileName LPSTR Points to a string that names the initialization file. 
If IpFileName does not contain a path to the file, Windows 
searches for the file in the Windows directory. 
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Return Value The return value specifies the result of the function. The return value is zero if the value 
that corresponds to the specified key name is not an integer or if the integer is negative. If 
the value that corresponds to the key name consists of digits followed by nonnumeric 
characters, the function returns the value of the digits. For example, if the entry Key- 
Name=102abc is accessed, the function returns 102. If the key is not found, this function 
returns the default value, nDefault. 


Comments The GetPrivateProfileInt function is not case dependent, so the strings in /pApplication- 
Name and IpKeyName may be in any combination of uppercase and lowercase letters. 


GetPrivateProfileString 


Syntax int GetPrivateProfileString(/pApplicationName, IpKeyName, lpDefault, 
IpReturnedString, nSize, lpFileName) 


This function copies a character string from the specified initialization file into the buffer 
pointed to by the /pReturnedString parameter. 


The function searches the file for a key that matches the name specified by the IpKeyName 
parameter under the application heading specified by the IpApplicationName parameter. If 
the key is found, the corresponding string is copied to the buffer. If the key does not exist, 
the default character string specified by the /pDefault parameter is copied. A string entry in 
the initialization file must have the following form: 


[application name] 
keyname = string 


If IpKeyName is NULL, the GetPrivateProfileString function enumerates all key names 
associated with IpApplicationName by filling the location pointed to by /pReturnedString 
with a list of key names (not values). Each key name in the list is terminated with a null 


character. 

Parameter Type/Description 

IpApplicationName LPSTR Points to the name of a Windows application that 
appears in the initialization file. 

IpKeyName_ | LPSTR Points to a key name that appears in the initializa- 
tion file. 

[pDefault LPSTR Specifies the default value for the given key if the 


key cannot be found in the initialization file. 
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Return Value 


Comments 


Parameter Type/Description | 

[pReturnedString LPSTR Points to the buffer that receives the character 
string. a 

nSize int Specifies the maximum number of characters (including 


the last null character) to be copied to the buffer. 


IpFileName LPSTR Points to a string that names the initialization file. 
If IpFileName does not contain a path to the file, Windows 
searches for the file in the Windows directory. 


The return value specifies the number of characters copied to the buffer identified by the 
[pReturnedString parameter, not including the terminating null character. If the buffer is 
not large enough to contain the entire string and pKeyName is not NULL, the return value 
is equal to the length specified by the nSize parameter. If the buffer is not large enough to 
contain the entire string and JpKeyName is NULL, the return value is equal to the length 
specified by the nSize parameter minus 2. 


GetPrivateProfileString is not case dependent, so the strings in /pApplicationName and 
IpKeyName may be in any combination of uppercase and lowercase letters. 


GetProcAddress 


Syntax 


Return Value 


FARPROC  GetProcAddress(hModule, lpProcName) 


This function retrieves the memory address of the function whose name Is pointed to by 
the IpProcName parameter. The GetProcAddress function searches for the function in the 
module specified by the hModule parameter, or in the current module if hModule is NULL. 
The function must be an exported function; the module’s definition file must contain an ap- 
propriate EXPORTS line for the function. 


Parameter Type/Description 
hModule HANDLE Identifies the library module that contains the function. 
IpProcName LPSTR Points to the function name, or contains the ordinal value 


of the function. If it is an ordinal value, the value must be in the low- 
order word and zero must be in the high-order word. The string must 
be a null-terminated character string. 


The return value points to the function’s entry point if the function is successful. Other- 
wise, itis NULL. 
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GetProfiletnt 


Comments 


GetProfileint 
Syntax 


Return Value 


If the JpProcName parameter is an ordinal value and a function with the specified ordinal 
does not exist in the module, GetProcAddress can still return a non-NULL value. In cases 
where the function may not exist, specify the function by name rather than ordinal value. 


Only use GetProcAddress to retrieve addresses of exported functions that belong to li- 
brary modules. The MakeProclInstance function can be used to access functions within 
different instances of the current module. 


The spelling of the function name (pointed to by /pProcName) must be identical to the 
spelling as it appears in the source library’s definition (.DEF) file. The function can be re- 
named in the definition file. 


WORD ~— GetProfileInt(pAppName, IpKeyName, nDefault) 


This function retrieves the value of an integer key from the Windows initialization file, 
WIN.INI. The function searches WIN.INI for a key that matches the name specified by the 
IpKeyName parameter under the application heading specified by the JpAppName parame- 
ter. An integer entry in WIN.INI must have the following form: 


[application name] 
keyname = value 


Parameter Type/Description 


IpAppName LPSTR Points to the name of a Windows application that appears 
in the Windows initialization file. 


IpKeyName LPSTR Points to a key name that appears in the Windows initiali- 
zation file. 


nDefault int Specifies the default value for the given key if the key cannot 
be found in the Windows initialization file. 


The return value specifies the result of the function. The return value is zero if the value 
that corresponds to the specified key name is not an integer or if the integer is negative. If 
the value that corresponds to the key name consists of digits followed by nonnumeric 
characters, the function returns the value of the digits. For example, if the entry Key- 
Name=102abc is accessed, the function returns 102. If the key is not found, this function 
returns the default value, nDefault. 
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GetProfileString 


Syntax 


’ Return Value 


Comments 


int GetProfileString(/pAppName, lpKeyName, IpDefault, lpReturnedString, nSize) 


This function copies a character string from the Windows initialization file, WIN.INI, into 
the buffer pointed to by the /pReturnedString parameter. The function searches WIN.INI 
for a key that matches the name specified by the p>KeyName parameter under the applica- 
tion heading specified by the JpAppName parameter. If the key is found, the corresponding 
string is copied to the buffer. If the key does not exist, the default character string specified 
by the /pDefault parameter is copied. A string entry in WIN.INI must have the following 
form: 


[application name] 
keyname = value 


If IpKeyName is NULL, the GetProfileString function enumerates all key names as- 
sociated with IpAppName by filling the location pointed to by /pReturnedString with a list 
of key names (not values). Each key name in the list is terminated with a null character. 


Parameter Type/Description 

[pAppName LPSTR Points to a null-terminated character string that 
names the application. 

IpKeyName LPSTR Points to a null-terminated character string that 
names a key. . 

IpDefault LPSTR Specifies the default value for the given key if the 
key cannot be found in the initialization file. 

IpReturnedString LPSTR Points to the buffer that receives the character string. 

nSize int Specifies the number of characters (including the last null 


character) that will be copied to the buffer. 


The return value specifies the number of characters copied to the buffer identified by the 
lpReturnedString parameter, not including the terminating null character. If the buffer is 
not large enough to contain the entire string and IpKeyName is not NULL, the return value 
is equal to the length specified by the nSize parameter. If the buffer is not large enough to 
contain the entire string and JpKeyName is NULL, the return value is equal to the length 
specified by the nSize parameter minus 2. 


GetProfileString is not case-dependent, so the strings in pAppName and IpKeyName may 
be in any combination of uppercase and lowercase letters. 
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GetProp 
Syntax HANDLE  GetProp(hWnd, IpString) 

This function retrieves a data handle from the property list of the specified window. The 

character string pointed to by the /pString parameter identifies the handle to be retrieved. 

The string and handle are assumed to have been added to the property list by using the Set- 

Prop function. 

Parameter Type/Description 

hWnd HWND Identifies the window whose property list is to be 
searched. 

IpString LPSTR Points to a null-terminated character string or an atom that 
identifies a string. If an atom is given, it must have been created pre- 
viously by using the AddAtom function. The atom, a 16-bit value, 
must be placed in the low-order word of the /pString parameter; the 
high-order word must be set to zero. 

Return Value The return value identifies the associated data handle if the property list contains the given 
string. Otherwise, it is NULL. 
Comments The value retrieved by the GetProp function can be any 16-bit value useful to the applica- 


tion. 


GetRgnBox 
Syntax int GetRgnBox(hRegn, lpRect) 


This function retrieves the coordinates of the bounding rectangle of the region specified by 
the hRgn parameter. 


Parameter Type/Description 
hRgn HRGN _Identifies the region. 
IpRect LPRECT Points to a RECT data structure to receive the 


coordinates of the bounding rectangle. 


Return Value The return value specifies the region’s type. It can be any of the following values. 
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Value Meaning 

COMPLEXREGION Region has overlapping borders. 
NULLREGION Region is empty. 
SIMPLEREGION Region has no overlapping borders. 


The return value is NULL if the hRgn parameter does not specify a valid region. 


GetROP2 

Syntax int GetROP2(hDC) 
This function retrieves the current drawing mode. The drawing mode specifies how the 
pen or interior color and the color already on the display surface are combined to yield a 
new color. . 
Parameter Type/Description 
hDC HDC Identifies the device context for a raster device. 

Return Value The return value specifies the drawing mode. For a list of the drawing modes, see Table 
4.16, “Drawing Modes,” in the SetROP2 function, later in this chapter. 

Comments For more information about the drawing modes, see Chapter 11, “Binary and Ternary 

Raster-Operation Codes,” in Reference, Volume 2. 
GetRValue 
Syntax BYTE GetRValue(rgbColor) 


This macro extracts the red value from an RGB color value. 


Parameter Type/Description 


rgbColor DWORD Specifies a red, a green, and a blue color field, each 
specifying the intensity of the given color. 


Return Value The return value specifies a byte that contains the red value of the rgbColor parameter. 
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GetScrollPos 


Comments 


GetScrollPos 
Syntax 


Return Value 


GetScrollRange 


Syntax 


The value OFFH corresponds to the maximum intensity value for a single byte; OOOH corre- 
sponds to the minimum intensity value for a single byte. 


int GetScrollPos(hWnd, nBar) 


This function retrieves the current position of a scroll-bar thumb. The current position is a 
relative value that depends on the current scrolling range. For example, if the scrolling 
range is 0 to 100 and the thumb is in the middle of the bar, the current position is 50. 


Parameter Type/Description 


hWnd HWND Identifies a window that has standard scroll bars or a 
scroll-bar control, depending on the value of the nBar parameter. 


nBar int Specifies the scroll bar to examine. It can be one of the fol- 
lowing values: 


Value Meaning 


SB_CTL Retrieves the position of a scroll-bar control. 
In this case, the hWnd parameter must be the 
window handle of a scroll-bar control. 


SB_HORZ Retrieves the position of a window’s horizon- 
tal scroll bar. 

SB_VERT Retrieves the position of a window’s vertical 
scroll bar. 


The return value specifies the current position of the scroll-bar thumb. 


void GetScrollRange(iWnd, nBar, lpMinPos, lpMaxPos) 


This function copies the current minimum and maximum scroll-bar positions for the given 
scroll bar to the locations specified by the /pMinPos and IpMaxPos parameters. Tf the 

given window does not have standard scroll bars or is not a scroll-bar control, then the Get- 
ScrollRange function copies zero to pMinPos and IpMaxPos. 
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Parameter Type/Description 


hWnd HWND Identifies a window that has standard scroll bars or a 
scroll-bar control, depending on the value of the nBar parameter. 


nBar int Specifies an integer value that identifies which scroll bar to 
retrieve. It can be one of the following values: 


Value Meaning 


SB_CTL Retrieves the position of a scroll-bar control; 
in this case, the hWnd parameter must be the 
handle of a scroll-bar control. 


SB_HORZ Retrieves the position of a window’s horizon- 
tal scroll bar. 
SB_VERT Retrieves the position of a window’s vertical 
scroll bar. 
IpMinPos LPINT Points to the integer variable that is to receive the min- 


imum position. 


IpMaxPos LPINT Points to the integer variable that is to receive the maxi- 
mum position. 


Return Value None. 


Comments The default range for a standard scroll bar is 0 to 100. The default range for a scroll-bar 
control is empty (both values are zero). 
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GetStockObject 
Syntax 


HANDLE GetStockObject(n/ndex) 


GetStockObject 


This function retrieves a handle to one of the predefined stock pens, brushes, or fonts. 


Parameter 


nIndex 


Type/Description 


int Specifies the type of stock object desired. It can be any one of 


the following values: 


BLACK_BRUSH 
DKGRAY_BRUSH 
GRAY_BRUSH 
HOLLOW_BRUSH 
LTGRAY_BRUSH 
NULL_BRUSH 
WHITE_BRUSH 
BLACK_PEN 
NULL_PEN 
WHITE_PEN 
ANSI_FIXED_FONT 
ANSI_VAR_FONT . 
DEVICE _DEFAULT_FONT 
OEM_FIXED_FONT 
SYSTEM_FONT 


Meaning 

Black brush 

Dark gray brush 

Gray brush 

Hollow brush 

Light gray brush 

Null brush 

White brush 

Black pen 

Null pen 

White pen 

ANSI fixed system font 
ANSI variable system font 
Device-dependent font 
OEM-dependent fixed font 


The system font. By default, 
Windows uses the system font 
to draw menus, dialog-box con- 
trols, and other text. In 
Windows versions 3.0 and later, 


the system font is proportional 


width; earlier versions of 
Windows use a fixed-width sys- 
tem font. 
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Return Value 


Comments 


Parameter Type/Description 

Value Meaning 

SYSTEM_FIXED_FONT The fixed-width system font 
used in earlier versions of 
Windows. This stock object is 
available for compatibility pur- 
poses. 

DEFAULT_PALETTE Default color palette. This 


palette consists of the 20 static 
colors always present in the sys- 
tem palette for matching colors 
in the logical palettes of back- 
ground windows. 


The return value identifies the desired logical object if the function is successful. Other- 
wise, itis NULL. 


The DKGRAY_BRUSH, GRAY_BRUSH, and LTGRAY_BRUSH objects should not be 
used as background brushes or for any other purpose in a window whose class does not 
specify CS_HREDRAW and CS_VREDRAW styles. Using a gray stock brush in such 
windows can lead to misalignment of brush patterns after a window is moved or sized. 
Stock-brush origins cannot be adjusted (for more information, see the SetBrushOrg func- 
tion, later in this chapter). 


GetStretchBlitMode 


Syntax 


Return Value 


int GetStretchBltMode(hDC) 


This function retrieves the current stretching mode. The stretching mode defines how infor- 
mation is to be added or removed from bitmaps that are stretched or compressed by using 
the StretchBlt function. 


Parameter Type/Description 


hDC HDC _ Identifies the device context. 


_ The return value specifies the current stretching mode. It can be WHITEONBLACK, 


BLACKONWHITE, or COLORONCOLOR. For more information, see the SetStretch- 
BltMode function, later in this chapter. 
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GetSubMenu 


GetSubMenu 
Syntax 


Return Value 


GetSysColor 
Syntax 


Return Value 


Comments 


HMENU- GetSubMenu(hMenu, nPos) 


This function retrieves the menu handle of a pop-up menu. 


Parameter 


hMenu 


nPos 


Type/Description 
HMENU Identifies the menu. 


int Specifies the position in the given menu of the pop-up menu. 
Position values start at zero for the first menu item. The pop-up 
menu’s integer ID cannot be used in this function. 


The return value identifies the given pop-up menu. It is NULL if no pop-up menu exists at 


the given position. 


DWORD ~ GetSysColor(/ndex) 


This function retrieves the current color of the display element specified by the nJndex par- 
ameter. Display elements are the various parts of a window and the Windows display that 
appear on the system display screen. 


Parameter 


nIndex 


Type/Description 


int Specifies the display element whose color is to be retrieved. 
For a list of the index values, see the SetSysColor function, later in 
this chapter. 


The return value specifies an RGB color value that names the color of the given element. 


System colors for monochrome displays are usually interpreted as various shades of gray. 
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GetSysModalWindow 
Syntax HWND ~~ GetSysModalWindow( ) 
This function returns the handle of a system-modal window, if one is present. 


This function-has no parameters. 


Return Value The return value identifies the system-modal window, if one is present. If no such window 
is present, the return value is NULL. 


GetSystemDirectory 
Syntax WORD GetSystemDirectory(/pBuffer, nSize) 


This function obtains the pathname of the Windows system subdirectory. The system sub- 
directory contains such files as Windows libraries, drivers, and font files. 


Parameter Type/Description 


lpBuffer LPSTR Points to the buffer that is to receive the null-terminated 
character string containing the pathname. 


nSize int Specifies the maximum size (in bytes) of the buffer. This value 
should be set to at least 144 to allow sufficient room in the buffer for 
the pathname. | 


Return Value The return value is the length of the string copied to /pBuffer, not including the terminating 
null character. If the return value is greater than nSize, the return value is the size of the 
buffer required to hold the pathname. The return value is zero if the function failed. 


Comments The pathname retrieved by this function does not end with a backslash (\), unless the sys- 
tem directory is the root directory. For example, if the system directory is named 
WINDOWS'SSYSTEM on drive C:, the pathname of the system subdirectory retrieved by 
this function is C\WINDOWS'S YSTEM. 
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GetSystemMenu 
Syntax HMENU~ GetSystemMenu(hWnd, bRevert) 


Return Value 


Comments 


This function allows the application to access the System menu for copying and modifica- 
tion. 


Parameter Type/Description 

hWnd HWND Identifies the window that will own a copy of the System 
menu. 

bRevert BOOL Specifies the action to be taken. 
If bRevert is: Description 
zero GetSystemMenu returns a handle to a copy of the 


System menu currently in use. This copy is ini- 
tially identical to the System menu, but can be 
modified. 


nonzero GetSystemMenu destroys the possibly modified 
copy of the System menu (if there is one) that 
belongs to the specified window and returns a 
handle to the original, unmodified version of the 
System menu. . 


The return value identifies the System menu if bRevert is nonzero and the System menu 
has been modified. If bRevert is nonzero and the System menu has not been modified, the 
return value is NULL. If bRevert is zero, the return value identifies a copy of the System 
menu. 


Any window that does not use the GetSystemMenu function to make its own copy of the 
System menu receives the standard System menu. 


The handle returned by the GetSystemMenu function can be used with the Append- 
Menu, InsertMenu or ModifyMenu functions to change the System menu. The System 
menu initially contains items identified with various ID values such as SC_CLOSE, 
SC_MOVE, and SC_SIZE. Menu items on the System menu send WM_SYSCOMMAND 
messages. All predefined System-menu items have ID numbers greater than OxFO000. If an 
application adds commands to the System menu, it should use ID numbers less than FOOO. 


Windows automatically grays items on the standard System menu, depending on the situa- 


tion. The application can carry out its own checking or graying by responding to the 
WM_INITMENU message, which is sent before any menu is displayed. 
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GetSystemMetrics 
Syntax int GetSystemMetrics(n/ndex) 


This function retrieves the system metrics. The system metrics are the widths and heights 
of various display elements of the Windows display. The GetSystemMetrics function can 
also return flags that indicate whether the current version is a debugging version, whether 
a mouse is present, or whether the meaning of the left and right mouse buttons have been 


exchanged. 
Parameter Type/Description 
nIndex int Specifies the system measurement to be retrieved. All measure- 
ments are given in pixels. The system measurement must be one of 
the values listed in Table 4.10, “System Metric Indexes.” 
Return Value The return value specifies the requested system metric. 
Comments System metrics depend on the system display and may vary from display to display. Table 


4.10 lists the system-metric values for the n/ndex parameter: 


Table 4.10 System Metric Indexes 


Index Meaning 

SM_CXSCREEN Width of screen. 

SM_CYSCREEN Height of screen. 

SM_CXFRAME Width of window frame that can be sized. 

SM_CYFRAME Height of window frame that can be sized. 
SM_CXVSCROLL Width of arrow bitmap on vertical scroll bar. 
SM_CYVSCROLL Height of arrow bitmap on vertical scroll bar. 
SM_CXHSCROLL Width of arrow bitmap on horizontal scroll bar. 
SM_CYHSCROLL Height of arrow bitmap on horizontal scroll bar. 
SM_CYCAPTION Height of caption. 

SM_CXBORDER Width of window frame that cannot be sized. 
SM_CYBORDER Height of window frame that cannot be sized. 
SM_CXDLGFRAME Width of frame when window has WS_DLGFRAME style. 
SM_CYDLGFRAME Height of frame when window has WS_DLGFRAME style. 
SM_CXHTHUMB Width of thumb box on horizontal scroll bar. 


SM_CYVTHUMB Height of thumb box on vertical scroll bar. 
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Table 4.10 System Metric Indexes (continued) 


Index 


SM_CXICON 
SM_CYICON 
SM_CXCURSOR 
SM_CYCURSOR 
SM_CYMENU 
SM_CXFULLSCREEN 
SM_CYFULLSCREEN 


SM_CYKANJIWINDOW 
SM_CXMINTRACK 
SM_CYMINTRACK 
SM_CXMIN 
SM_CYMIN 
SM_CXSIZE 
SM_CYSIZE 
SM_MOUSEPRESENT 
SM_DEBUG 
SM_SWAPBUTTON 


GetSystemPaletteEntries 
WORD = GetSystemPaletteEntries(iDC, wStartIndex, wNumEntries, lpPaletteEntries) 


Syntax 


Meaning 


Width of icon. 

Height of icon. 

Width of cursor. 

Height of cursor. 

Height of single-line menu bar. 

Width of window client area for full-screen window. 


Height of window client area for full-screen window (equiv- 
alent to the height of the screen minus the height of the 
window caption). 


Height of Kanji window. 

Minimum tracking width of window. 

Minimum tracking height of window. 

Minimum width of window. 

Minimum height of window. 

Width of bitmaps contained in the title bar. 

Height of bitmaps contained in the title bar. ¢ 
Nonzero if mouse hardware installed. 

Nonzero if Windows debugging version. = 


Nonzero if left and right mouse buttons swapped. 


This function retrieves a range of palette entries from the system palette. 


Parameter 


hDC HDC 


wStartIndex 


Type/Description 


Identifies the device context. 


WORD _ Specifies the first entry in the system palette to be re- 


trieved. 


wNumEntries 


WORD Specifies the number of entries in the system palette 


to be retrieved. 


GetSystemPaletteUse 4-214 


Return Value 


Parameter Type/Description 


IpPaletteEntries LPPALETTEENTRY Points to an array of PALETTE- 
ENTRY data structures to receive the palette entries. The array 
must contain at least as many data structures as specified by the 
wNumEntries parameter. 


The return value is the number of entries retrieved from the system palette. It is zero if the 
function failed. 


GetSystemPaletteUse 


Syntax 


Return Value 


WORD GetSystemPaletteUse(ADC) 


This function determines whether an application has access to the full system palette. By 
default, the system palette contains 20 static colors which are not changed when an applica- 
tion realizes its logical palette. An application can gain access to most of these colors by 
calling the SetSystemPaletteUse function. 


The device context identified by the ADC parameter must refer to a device that supports 
color palettes. 


Parameter Type/Description 


hDC HDC Identifies the device context. 


The return value specifies the current use of the system palette. It is either of the following 
values: 


Value Meaning 

SYSPAL_NOSTATIC System palette contains no static colors except black and 
white. 

SYSPAL_STATIC System palette contains static colors which will not 


change when an application realizes its logical palette. 
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Scie een 


GetTabbedTextExtent 


Syntax 


Return Value 


Comments 


DWORD  GetTabbedTextExtent(/iDC, IpString, nCount, nTabPositions, 
lpnTabStopPositions) 


This function computes the width and height of the line of text pointed to by the /pString 
parameter. If the string contains one or more tab characters, the width of the string is based 
upon the tab stops specified by the /pnTabStopPositions parameter. The GetTabbedTex- 
tExtent function uses the currently selected font to compute the dimensions of the string. 
The width and height (in logical units) are computed without considering the current clip- 
ping region. 


Parameter Type/Description 

hDC HDC Identifies the device context. 

[pString LPSTR Points to a text string. 

nCount int Specifies the number of characters in the text string. 
nTabPositions int Specifies the number of tab-stop positions in the array 


to which the /pnTabStopPositions points. 


lpnTabStopPositions LPINT Points to an array of integers containing the tab- 
stop positions in pixels. The tab stops must be sorted in 
increasing order; back tabs are not allowed. 


The return value specifies the dimensions of the string. The height is in the high-order 
word; the width is in the low-order word. 


Since some devices do not place characters in regular cell arrays (that is, they carry out 
kerning), the sum of the extents of the characters in a string may not be equal to the extent 
of the string. 


If the nTabPositions parameter is zero and the [pnTabStopPositions parameter is NULL, 
tabs are expanded to eight average character widths. 


If nTabPositions is 1, the tab stops will be separated by the distance specified by the first 
value in the array to which [pnTabStopPositions points. 


If IpnTabStopPositions points to more than a single value, then a tab stop is set for each 
value in the array, up to the number specified by nTabPositions. 
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GetTempDrive 
Syntax BYTE GetTempDrive(cDriveLetter) 


This function takes a drive letter or zero and returns a letter that specifies the optimal drive 
for a temporary file (the disk drive that can provide the best access time during disk opera- 
tions with a temporary file). 


The GetTempDrive function returns the drive letter of a hard disk if the system has one. If 
the cDriveLetter parameter is zero, the function returns the drive letter of the current disk; 
if cDriveLetter is a letter, the function returns the letter of that drive or the letter of another 
available drive. 


Parameter Type/Description 


cDriveLetter BYTE Specifies a disk-drive letter. 


Return Value The return value specifies the optimal disk drive for temporary files. 
GetTempFileName | 
Syntax int GetTempFileName(cDriveLetter, IpPrefixString, wUnique, lpTempFileName) 


This function creates a temporary filename of the following form: 
drive:\path\prefixuuuu.tmp 


In this syntax line, drive is the drive letter specified by the cDriveLetter parameter; path is 
the pathname of the temporary file (either the root directory of the specified drive or the 
directory specified in the TEMP environment variable); prefix is all the letters (up to the 
first three) of the string pointed to by the /pPrefixString parameter; and uuuu is the hex- 
adecimal value of the number specified by the wUnique parameter. 


Parameter Type/Description 


cDriveLetter BYTE Specifies the suggested drive for the temporary 
filename. If cDriveLetter is zero, the default drive is used. 


IpPrefixString LPSTR Points to a null-terminated character string to be used — 
as the temporary filename prefix. This string must consist of 
characters in the OEM-defined character set. 


wUnique WORD Specifies an unsigned short integer. 
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Return Value 


Comments 


GetTextAlign 
Syntax 


Parameter Type/Description 


IpTempFileName LPSTR Points to the buffer that is to receive the temporary 

. filename. This string consists of characters in the OEM-defined 
character set. This buffer should be at least 144 bytes in length 
to allow sufficient room for the pathname. 


The return value specifies a unique numeric value used in the temporary filename. If a non- 
zero value was given for the wUnique parameter, the return value specifies this same num- 
ber. 


To avoid problems resulting from converting OEM character an string to an ANSI string, 
an application should call the _lopen function to create the temporary file. 


The GetTempFileName function uses the suggested drive letter for creating the temporary 
filename, except in the following cases: 


m Ifahard disk is present, GetTempFileName always uses the drive letter of the first 
hard disk. 


= Otherwise, if a TEMP environment variable is defined and its value begins with a drive 
letter, that drive letter is used. 


If the TF_FORCEDRIVE bit of the cDriveLetter parameter is set, the above exceptions do 
not apply. The temporary filename will always be created in the current directory of the 
drive specified by cDriveLetter, regardless of the presence of a hard disk or the TEMP en- 
vironment variable. 


If the wUnique parameter is zero, GetTempFileName attempts to form a unique number 
based on the current system time. If a file with the resulting filename exists, the number is 
increased by one and the test for existence is repeated. This continues until a unique 
filename is found; GetTempFileName then creates a file by that name and closes it. No at- 
tempt is made to create and open the file when wUnique is nonzero. 


WORD = GetTextAlign(iDC) 


This function retrieves the status of the text-alignment flags. The text-alignment flags de- 
termine how the TextOut and ExtTextOut functions align a string of text in relation to the 
string’s starting point. 
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Parameter Type/Description 
hDC HDC Identifies the device context. 
Return Value The return value specifies the status of the text-alignment flags. The return value is a com- 


bination of one or more of the following values: 


Value Meaning 


TA_BASELINE Specifies alignment of the x-axis and the baseline of the 
chosen font within the bounding rectangle. 


TA_BOTTOM Specifies alignment of the x-axis and the bottom of the 
bounding rectangle. 


TA_CENTER Specifies alignment of the y-axis and the center of the bound- 
ing rectangle. 


TA_LEFT Specifies alignment of the y-axis and the left side of the 
bounding rectangle. 


TA_NOUPDATECP Specifies that the current position is not updated. 


TA_RIGHT Specifies alignment of the y-axis and the right side of the 
bounding rectangle. 
TA_TOP Specifies alignment of the x-axis and the top of the bounding 
rectangle. 
TA_UPDATECP Specifies that the current position is updated. 
Comments The text-alignment flags are not necessarily single-bit flags and may be equal to zero. To 


verify that a particular flag is set in the return value of this function, build an application 
that will perform the following steps: 


1. Apply the bitwise OR operator to the flag and its related flags. 
The following list shows the groups of related flags: 
m TA_LEFT, TA_CENTER, and TA_RIGHT 
m TA_BASELINE, TA_BOTTOM, and TA_TOP 
m= TA_NOUPDATECP and TA_UPDATECP 
2. Apply the bitwise AND operator to the result and the return value. 


3. Test for the equality of this result and the flag. 
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The following example shows a method for determining which horizontal-alignment flag 
is set: 


switch ((TA_LLEFT | TA_RIGHT | TA_CENTER) & GetTextAlign(hDC)) { 
case TA_LEFT 


case TA_RIGHT 


case TA_CENTER 


GetTextCharacterExtra 
Syntax int GetTextCharacterExtra(hDC) 


This function retrieves the current intercharacter spacing. The intercharacter spacing de- 
fines the extra space (in logical units) that the TextOut or ExtTextOut functions add to 
each character as they write a line. The spacing is used to expand lines of text. 


If the current mapping mode is not MM_TEXT, the GetTextCharacterExtra function 
~ transforms and rounds the result to the nearest unit. 


Parameter Type/Description 

hDC HDC Identifies the device context. 
Return Value The return value specifies the current intercharacter spacing. 
GetTextColor 
Syntax DWORD ~ GetTextColor(hDC) 


This function retrieves the current text color. The text color defines the foreground color of 
characters drawn by using the TextOut or ExtTextOut functions. 
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Return Value 


GetTextExtent 
Syntax 


Return Value 


Comments 


GetTextFace 
Syntax 


Parameter Type/Description 


hDC HDC Identifies the device context. 


The return value specifies the current text color as an RGB color value. 


DWORD  GetTextExtent(hDC, IpString, nCount) 


This function computes the width and height of the line of text pointed to by the /pString 
parameter. The GetTextExtent function uses the currently selected font to compute the di- 
mensions of the string. The width and height (in logical units) are computed without con- 
sidering the current clipping region. 


Parameter Type/Description 

hDC HDC Identifies the device context. 

IpString LPSTR Points to a text string. 

nCount int Specifies the number of characters in the text string. 


The return value specifies the dimensions of the string. The height is in the high-order 
word; the width is in the low-order word. 


Since some devices do not place characters in regular cell arrays (that is, they carry out 
kerning), the sum of the extents of the characters in a string may not be equal to the extent 
of the string. 


int GetTextFace(hDC, nCount, lpFacename) 


This function copies the typeface name of the selected font into a buffer pointed to by the 
IpFacename parameter. The typeface name is copied as a null-terminated character string. 


- The nCount parameter specifies the maximum number of characters to be copied. If the 


name is longer than the number of characters specified by nCount, it is truncated. 
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Parameter Type/Description 

hDC HDC Identifies the device context. 

nCount int Specifies the size of the buffer in bytes. 

lpFacename LPSTR Points to the buffer that is to receive the typeface name. 
Return Value The return value specifies the actual number of bytes copied to the buffer. It is zero if an 


error OCCUTrS. 


GetTextMetrics 
Syntax BOOL GetTextMetrics(DC, [pMetrics) 


This function fills the buffer pointed to by the /pMetrics parameter with the metrics for the 
selected font. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpMetrics LPTEXTMETRIC Points to the TEXTMETRIC data structure 


that is to receive the metrics. 


Return Value The return value specifies the outcome of the function. It is nonzero if the function is 
successful. Otherwise, it is zero. 


GetThresholdEvent 
Syntax LPINT GetThresholdEvent( ) 


This function retrieves a flag that identifies a recent threshold event. A threshold event is 
any transition of a voice queue from n to n — | where n is the threshold level in notes. 


This function has no parameters. 


Return Value The return value points to a short integer that specifies a threshold event. 
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GetThresholdStatus 
Syntax int GetThresholdStatus( ) 


This function retrieves the threshold-event status for each voice. Each bit in the status rep- 
resents a voice. If a bit is set, the voice-queue level is currently below threshold. 


The GetThresholdStatus function also clears the threshold-event flag. 


This function has no parameters. 


Return Value The return value specifies the status flags of the current threshold event. 
GetTickCount 
Syntax DWORD  GetTickCount( ) 


This function obtains the number of milliseconds that have elapsed since the system was 
started. . 


This function has no parameters. 


Return Value The return value specifies the number of milliseconds that have elapsed since the system 
was started. 

Comments The count is accurate within +55 milliseconds. 

GetTopWindow 

Syntax HWND_  GetTopWindow(hWnd) 


This function searches for a handle to the top-level child window that belongs to the parent 
window associated with the hWnd parameter. If the window has no children, this function 


returns NULL. 
Parameter Type/Description 
hWnd HWND Identifies the parent window. 
Return Value The return value identifies a handle to the top-level child window in a parent window’s 


linked list of child windows. If no child windows exist, it is NULL. 
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GetUpdateRect 
Syntax BOOL GetUpdateRect(hWnd, IpRect, bErase) 


This function retrieves the coordinates of the smallest rectangle that completely encloses 
the update region of the given window. If the window was created with the CS_OWNDC 
style and the mapping mode is not MM_TEXT, the GetUpdateRect function gives the 
rectangle in logical coordinates. Otherwise, GetUpdateRect gives the rectangle in client 
coordinates. If there is no update region, GetUpdateRect makes the rectangle empty (sets 
all coordinates to zero). 


The bErase parameter specifies whether GetUpdateRect should erase the background of 
the update region. If bErase is TRUE and the update region is not empty, the background 
is erased. To erase the background, GetUpdateRect sends a WM_ERASEBKGND 
message to the given window. 


Parameter Type/Description 

hWnd HWND Identifies the window whose update region is to be re- 
trieved. 

IpRect LPRECT Points to the RECT data structure that is to receive the 


client coordinates of the enclosing rectangle. 


bErase BOOL | Specifies whether the background in the update region is to 
be erased. 
Return Value The return value specifies the status of the update region of the given window. It is non- 


zero if the update region is not empty. Otherwise, it is zero. 
Comments The update rectangle retrieved by the BeginPaint function is identical to that retrieved by 
the GetUpdateRect function. 


BeginPaint automatically validates the update region, so any call to GetUpdateRect 
made immediately after the BeginPaint call retrieves an empty update region. 


GetUpdateRgn 
Syntax int GetUpdateRgn(iWnd, hRegn, fErase) 
This function copies a window’s update region into a region identified by the ARgn parame- 


ter. The coordinates of this region are relative to the upper-left corner of the window 
(client coordinates). 
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Parameter —‘ Type/Description 

hWnd HWND Identifies the window that contains the region to be up- 
dated. 

hRgn HRGN Identifies the update region. 

fErase BOOL _ Specifies whether or not the window background should be 


erased and nonclient areas of child windows should be drawn. If it is 
zero, no drawing is done. 


Return Value The return value specifies a short-integer flag that indicates the type of resulting region. It 
can be any one of the following values: 


Value Meaning 
COMPLEXREGION The region has overlapping borders. 
ERROR No region was created. 
NULLREGION The region is empty. 
SIMPLEREGION The region has no overlapping borders. 
| Comments BeginPaint automatically validates the update region, so any call to GetUpdateRgn made 


immediately after the BeginPaint call retrieves an empty update region. 


GetVersion 
Syntax WORD = GetVersion( ) 
This function returns the current version number of Windows. 
This function has no parameters. 
Return Value The return value specifies the major and minor version numbers of Windows. The high- 


order byte specifies the minor version (revision) number; the low-order byte specifies the 
major version number. 
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GetViewportExt 
Syntax DWORD  GetViewportExt(hDC) 


This function retrieves the x- and y-extents of the device context’s viewport. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
Return Value The return value specifies the x- and y-extents (in device units). The y-extent is in the high- 


order word; the x-extent is in the low-order word. 


GetViewportOrg 
Syntax DWORD  GetViewportOrg(hDC) 


This function retrieves the x- and y-coordinates of the origin of the viewport associated 
with the specified device context. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
Return Value The return value specifies the origin of the viewport (in device coordinates). The y-coordi- 


nate is in the high-order word; the x-coordinate is in the low-order word. 


GetWindow 
Syntax HWND_  GetWindow(hWnd, wCma) 


This function searches for a handle to a window from the window manager’s list. The 
window-manager’s list contains entries for all top-level windows, their associated child 
windows, and the child windows of any child windows. The wCmd parameter specifies the 
relationship between the window identified by the hWnd parameter and the window whose 
handle is returned. 
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Return Value 


GetWindowDC 
Syntax 


Parameter Type/Description 
hWnd HWND Identifies the original window. 
wCmd WORD _Specifies the relationship between the original window 


and the returned window. It may be one of the following values: 


Value Meaning . 

GW_CHILD Identifies the window’s first child 
window. 

GW_HWNDFIRST Returns the first sibling window for 


a child window. Otherwise, it re- 
turns the first top-level window in 
the list. 


GW_HWNDLAST Returns the last sibling window for 
a child window. Otherwise, it re- 
turns the last top-level window in 
the list. 


GW_HWNDNEXT Returns the window that follows the 
given window on the window 
manager’s list. 


GW_HWNDPREV Returns the previous window on the 
window manager’s list. 


GW_OWNER Identifies the window’s owner. 


The return value identifies a window. It is NULL if it reaches the end of the window 
manager’s list or if the wCmd parameter is invalid. 


HDC GetWindowDC(hWnd) 


This function retrieves the display context for the entire window, including caption bar, 
menus, and scroll bars. A window display context permits painting anywhere in a window, 
including the caption bar, menus, and scroll bars, since the origin of the context is the 
upper-left corner of the window instead of the client area. 
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Return Value 


Comments 


GetWindowExt 


Syntax 


Return Value 


GetWindowDC assigns default attributes to the display context each time it retrieves the 
context. Previous attributes are lost. 


Parameter Type/Description 
hWnd HWND Identifies the window whose display context is to be re- 
trieved. 


The return value identifies the display context for the given window if the function is 
successful. Otherwise, it is NULL. 


The GetWindowDC function is intended to be used for special painting effects within a 
window’s nonclient area. Painting in nonclient areas of any window is not recommended. 


The GetSystemMetrics function can be used to retrieve the dimensions of various parts of 
the nonclient area, such as the caption bar, menu, and scroll bars. 


After painting is complete, the ReleaseDC function must be called to release the display 
context. Failure to release a window display context will have serious effects on painting 
requested by applications. 


DWORD GetWindowExt(ADC) 


This function retrieves the x- and y-extents of the window associated with the specified 
device context. 


Parameter Type/Description 


hDC HDC Identifies the device context. 


The return value specifies the x- and y-extents (in logical units). The y-extent is in the high- 
order word; the x-extent is in the low-order word. 
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GetWindowLong 
Syntax LONG GetWindowLong(hWnd, nIndex) 


This function retrieves information about the window identified by the hWnd parameter. 


Parameter Type/Description 
hWnd HWND Identifies the window. 
nIndex int Specifies the byte offset of the value to be retrieved. It can also 


be one of the following values: 


Value Meaning 
GWL_EXSTYLE Extended window style 
GWL_STYLE Window style 
GWL_WNDPROC Long pointer to the window function 
Return Value The return value specifies information about the given window. 
_ Comments To access any extra four-byte values allocated when the window-class structure was 


created, use a positive byte offset as the index specified by the n/ndex parameter, starting 
at zero for the first four-byte value in the extra space, 4 for the next four-byte value and so 
on. 


GetWindowOrg 
Syntax DWORD GetWindowOrg(iDC) 


This function retrieves the x- and y-coordinates of the origin of the window associated with 
the specified device context. 


Parameter Type/Description 
hDC HDC | Identifies the device context. 
Return Value The return value specifies the origin of the window (in logical coordinates). The y-coordi- 


nate is in the high-order word; the x-coordinate is in the low-order word. 
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GetWindowRect 
Syntax void GetWindowRect(hWnd, [pRect) 


Return Value 


This function copies the dimensions of the bounding rectangle of the specified window 
into the structure pointed to by the /pRect parameter. The dimensions are given in screen 
coordinates, relative to the upper-left corner of the display screen, and include the caption, 
border, and scroll bars, if present. 


Parameter Type/Description 
hWnd HWND Identifies the window. 
IpRect LPRECT Points to a RECT data structure that contains the screen 


coordinates of the upper-left and lower-right corners of the window. 


None. 


GetWindowsDirectory 


Syntax 


Return Value 


Comments 


WORD GetWindowsDirectory(/pBuffer, nSize) 


This function obtains the pathname of the Windows directory. The Windows directory con- 
tains such files as Windows applications, initialization files, and help files. 


Parameter Type/Description 


IpBuffer LPSTR Points to the buffer that is to receive the null-terminated 
character string containing the pathname. 


nSize int Specifies the maximum size (in bytes) of the buffer. This value 
should be set to at least 144 to allow sufficient room in the buffer for 
the pathname. 


The return value is the length of the string copied to /pBuffer, not including the terminating 
null character. If the return value is greater than nSize, the return value is the size of the 
buffer required to hold the pathname. The return value is zero if the function failed. 


The pathname retrieved by this function does not end with a backslash (\), unless the 
Windows directory is the root directory. For example, if the Windows directory is named 
WINDOWS on drive C:, the pathname of the Windows directory retrieved by this function 
is C\WINDOWS. If Windows was installed in the root directory of drive C:, the Pe 
retrieved by this function is C:\ 
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GetWindowTask 


Syntax 


Return Value 


GetWindowText 


Syntax 


Return Value 


Comments 


HANDLE GetWindowTask(hWna) 


This function searches for the handle of a task associated with the hWnd parameter. A task 
is any program that executes as an independent unit. All applications are executed as tasks. 
Each instance of an application is a task. 


Parameter Type/Description 


hWnd HWND Identifies the window for which a task handle is retrieved. 


The return value identifies the task associated with a particular window. 


int GetWindowText(iWnd, IpString, nMaxCount) 


This function copies the given window’s caption title (if it has one) into the buffer pointed 
to by the /pString parameter. If the hWnd parameter identifies a control, the GetWin- 
dowText function copies the text within the control instead of copying the caption. 


Parameter Type/Description 

hWnd HWND Identifies the window or control whose caption or text is 
to be copied. 

IpString LPSTR Points to the buffer that is to receive the copied string. 

nMaxCount int Specifies the maximum number of characters to be copied to 


the buffer. If the string is longer than the number of characters 
specified in the nMaxCount parameter, it is truncated. 


The return value specifies the length of the copied string. It is zero if the window has no 
caption or if the caption is empty. 


This function causes a WM_GETTEXT message to be sent to the given window or control. 
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GetWindowTextLength 
Syntax int GetWindowTextLength(hWnd) 


This function returns the length of the given window’s caption title. If the hWnd parameter 
identifies a control, the GetWindowTextLength function returns the length of the text 
within the control instead of the caption. 


Parameter Type/Description 

hWnd HWND Identifies the window or control. 
Return Value The return value specifies the text length. It is zero if no such text exists. 
GetWindowWord 
Syntax WORD = GetWindowWord(hWnd, nIndex) 


This function retrieves information about the window identified by hWnd. 


Parameter Type/Description F 
hWnd HWND Identifies the window. 
nIndex int Specifies the byte offset of the value to be retrieved. It can 


also be one of the following values: 


Value Meaning 


GW W_HINSTANCE Instance handle of the module that 
owns the window. 


GW W_HWNDPARENT Handle of the parent window, if 
any. The SetParent function 
changes the parent window of a 
child window. An application 
should not call the SetWin- 
dowLong function to change the 
parent of a child window. 


GWW_ID Control ID of the child window. 


Return Value The return value specifies information about the given window. 
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Comments To access any extra two-byte values allocated when the window-class structure was 
created, use a positive byte offset as the index specified by the n/ndex parameter, starting 
at zero for the first two-byte value in the extra space, 2 for the next two-byte value and so 
on. 


GetWinFlags 
Syntax DWORD = GetWinFlags( ) 


This function returns a 32-bit value containing flags which specify the memory configura- 
tion under which Windows is running. 


This function has no parameters. 


Return Value The return value contains flags specifying the current memory configuration. These flags 
may be any of the following values: 


Value Meaning 

WEF_80x87 System contains an Intel math coprocessor. 

WF_CPU086 System CPU is an 8086. 

WF_CPUI86 System CPU is an 80186. 

WF_CPU286 System CPU is an 80286. 

WF_CPU386 System CPU is an 80386. 

WF_CPU486 System CPU is an 80486. 

WF_ENHANCED Windows is running in 386 enhanced mode. The 
WF_PMODE flag is always set when WF_ENHANCED 
is set. 

WF_LARGEFRAME Windows is running in EMS large-frame memory con- 
figuration. 

WF_PMODE Windows is running in protected mode. This flag is al- 


ways set when either WF_ENHANCED or 
WF_STANDARD is set. 


WF_SMALLFRAME Windows is running in EMS small-frame memory con- 
. figuration. 
WF_STANDARD Windows is running in standard mode. The 


WF_PMODE flag is always set when WF_STANDARD 
is set. 
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If neither WFE_ENHANCED nor WF_STANDARD is set, Windows is running in real 
mode. 


GlobalAddAtom 
Syntax ATOM GlobalAddAtom(/pString) 


This function adds the character string pointed to by the /pString parameter to the atom 
table and creates a new global atom that uniquely identifies the string. A global atom is an 
atom that is available to all applications. The atom can be used in a subsequent Global- 
GetAtomName function to retrieve the string from the atom table. 


The GlobalAddAtom function stores no more than one copy of a given string in the atom 
table. If the string is already in the table, the function returns the existing atom value and 
increases the string’s reference count by one. The string’s reference count is a number that 
specifies the number of times GlobalAddAtom has been called for a particular string. 


Parameter Type/Description 


lpString LPSTR Points to the character string to be added to the table. 
The string must be a null-terminated character string. 


Return Value The return value identifies the newly created atom if the function is successful. Otherwise, 
it is NULL. 

Comments The atom values returned by GlobalAddAtom are within the range 0xCO00 to OxXFFFF. 

GlobalAlloc 

Syntax HANDLE GlobalAlloc(wFlags, dwBytes) 


This function allocates the number of bytes of memory specified by the dwBytes parameter 
from the global heap. The memory can be fixed or moveable, depending on the memory 
type specified by the wFlags parameter. 
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Parameter Type/Description 


wFlags WORD Specifies one or more flags that tell the GlobalAlloc 
function how to allocate the memory. It can be one or more of the 
following values: 


Value Meaning 


GMEM_DDESHARE Allocates sharable memory. This 
is used for dynamic data exchange 
(DDE) only. Note, however, that 
Windows automatically discards 
memory allocated with this at- 
tribute when the application that 
allocated the memory terminates. 


GMEM_DISCARDABLE Allocates discardable memory. 
Can only be used with 
GMEM_MOVEABLE. 


a. GMEM_FIXED Allocates fixed memory. 
u GMEM_MOVEABLE Allocates moveable memory. Can- 
not be used with GMEM_FIXED. 
GMEM_NOCOMPACT Does not compact or discard to 
satisfy the allocation request. 
GMEM_NODISCARD Does not discard to satisfy the allo- 
cation request. 
GMEM_NOT_BANKED Allocates non-banked memory. 


Cannot be used with 
GMEM_NOTIFY. 


GMEM_NOTIFY Calls the notification routine if the 
memory object is ever discarded. 

GMEM_ZEROINIT Initializes memory contents to 
zero. 


Choose GMEM_FIXED or GMEM_MOVEABLE, and then com- 
bine others as needed by using the bitwise OR operator. 


dwBytes DWORD Specifies the number of bytes to be allocated. 


Return Value The return value identifies the allocated global memory if the function is successful. Other- 
wise, itis NULL. 
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GlobalCompact 


Comments 


GlobalCompact 


Syntax 


Return Value 


If this function is successful, it allocates at least the amount requested. The actual amount 
allocated may be greater, and the application can use the entire amount. To determine the 
actual amount allocated, call the GlobalSize function. 


The largest block of memory that an application can allocate is 1 MB in standard mode 
and 64 MB in 386 enhanced mode. 


DWORD_ GlobalCompact(dwMinFree) 


This function generates the number of free bytes of global memory specified by the 
dwMinF ree parameter by compacting and, if necessary, discarding from the system’s 
global heap. The function always compacts memory before checking for free memory. It 
then checks the global heap for the number of contiguous free bytes specified by the 
dwMinFree parameter. If the bytes do not exist, the GlobalCompact function discards un- 
locked discardable blocks until the requested space is generated, whenever possible. 


Parameter Type/Description 


dwMinFree DWORD Specifies the number of free bytes desired. 


The return value specifies the number of bytes in the largest block of free global memory. 


Comments If dwMinF ree is zero, the return value specifies the number of bytes in the largest free seg- 
ment that Windows can generate if it removes all discardable segments. 
If an application uses the return value as the dwBytes parameter to the GlobalAlloc func- 
tion, the GMEM_NOCOMPACT or GMEM_NODISCARD flags should not be used. 
GlobalDeleteAtom 
_ Syntax ATOM GlobalDeleteAtom(nAtom) 


This function decreases the reference count of a global atom by one. If the atom’s 
reference count becomes zero, this function removes the associated string from the atom 
table. (A global atom is an atom that is available to all Windows applications.) 


An atom’s reference count specifies the number of times the atom has been added to the 
atom table. The GlobalAddAtom function increases the count on each call; the Global- 
DeleteAtom function decreases the count on each call. GlobalDeleteAtom removes the 
string only if the atom’s reference count is zero. 
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Return Value 


GlobalDiscard 
Syntax 


Return Value 


Comments 


Parameter Type/Description 


nAtom ATOM Identifies the atom and character string to be deleted. 


The return value specifies the outcome of the function. It is NULL if the function is 
successful. It is equal to nAtom if the function failed and the atom has not been deleted. 


HANDLE  GlobalDiscard(hMem) 


This function discards a global memory block specified by the hMem parameter. The lock | 
count of the memory block must be zero. 


The global memory block is removed from memory, but its handle remains valid. An appli- 
cation can subsequently pass the handle to the GlobalReAlloc function to allocate another 
global memory block identified by the same handle. 


Parameter Type/Description 
hMem HANDLE Identifies the global memory block to be dis- 
carded. 


The return value identifies the discarded block if the function is successful. Otherwise, it is 
zero. 


The GlobalDiscard function discards only global objects that an application allocated 
with the GMEM_DISCARDABLE and GMEM_MOVEABLE flags set. The function fails 
if an application attempts to discard a fixed or locked object. 


GlobalDosAlloc 


Syntax 


DWORD — GlobalDosAlloc(dwBytes) 


This function allocates global memory which can be accessed by DOS running in real 
mode. The memory is guaranteed to exist in the first megabyte of linear address space. 


Parameter Type/Description 


dwBytes DWORD Specifies the number of bytes to be allocated. 
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GlobalDosFree 


Return Value 


Comments 


The return value contains a paragraph-segment value in its high-order word and a selector 
in its low-order word. An application can use the paragraph-segment value to access 
memory in real mode and the selector to access memory in protected mode. If Windows is 
running in real mode, the high-order and low-order words will be equal. If Windows can- 
not allocate a block of memory of the requested size, the return value is NULL. 


An application should not use this function unless it is absolutely necessary. The memory 
pool from which the object is allocated is a scarce system resource. 


GlobalDosFree 


Syntax 


Return Value 


WORD ~ GlobalDosFree(wSelector) 


This function frees a block of global memory previously allocated by a call to the Global- 
DosAlloc function. 


Parameter Type/Description 


wSelector WORD Specifies the memory to be freed. 


The return value identifies the outcome of the function. It is NULL if the function is 
successful. Otherwise, it is equal to wSelector. 


GlobalFindAtom 


Syntax 


Return Value 


ATOM _— GlobalFindAtom(/pString) 


This function searches the atom table for the character string pointed to by the /pString par- 
ameter and retrieves the global atom associated with that string. (A global atom is an atom 
that is available to all Windows applications.) 


Parameter Type/Description 


IpString LPSTR Points to the character string to be searched for. The string 
must be a null-terminated character string. 


The return value identifies the global atom associated with the given string. It is NULL if 
the string is not in the table. 


GlobalFix 
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GlobalFix 


Syntax 


Return Value 


Comments 


GlobalFlags 
Syntax 


Return Value 


void GlobalFix(hMem) 


This function prevents the global memory block identified by the hMem parameter from 
moving in linear memory. The block is locked into linear memory at its current address 
and its lock count is increased by one. Locked memory is not subject to moving or dis- 
carding except when the memory block is being reallocated by the GlobalReAlloc func- 
tion. The block remains locked in memory until its lock count is decreased to zero. 


Each time an application calls GlobalFix for a memory object, it must eventually call 
GlobalUnfix for the object. The GlobalUnfix function decreases the lock count for the ob- 
ject. Other functions also can affect the lock count of a memory object. See the description 
of the GlobalFlags function for a list of the functions that affect the lock count. 


Parameter Type/Description 
hMem HANDLE Identifies the global memory block. 
None. 


Calling this function interferes with Windows memory management and results in linear- 
address fragmentation. Very few applications need to fix memory in linear address space. 


WORD = GlobalFlags(iMem) 


This function returns information about the global memory block specified by the hMem 
parameter. 


Parameter Type/Description 


hMem HANDLE Identifies the global memory block. 


The return value specifies a memory-allocation flag in the high byte. The flag will be one 
of the following values: 
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Value Meaning 
GMEM_DDESHARE The block can be shared. This is used for dynamic 
data exchange (DDE) only. 
GMEM_DISCARDABLE The block can be discarded. 
GMEM_DISCARDED The block has been discarded. 
GMEM_NOT_BANKED The block cannot be banked. 
The low byte of the return value contains the lock count of the block. Use the 
GMEM_LOCKCOUNT mask to retrieve the lock-count value from the return value. 
Comments To test whether or not an object can be discarded, AND the return value of GlobalFlags 
with GMEM_DISCARDABLE. 
The following functions can affect the lock count of a global memory block: 
Increases Lock Count Decreases Lock Count 
GlobalF ix GlobalUnfix 
GlobalLock GlobalUnlock 
GlobalWire GlobalUnWire 
LockSegment UnlockSegment 
GlobalFree 
Syntax HANDLE GlobalFree(iMem) 


Return Value 


This function frees the global memory block identified by the ;Mem parameter and 
invalidates the handle of the memory block. 


Parameter Type/Description 


hMem HANDLE Identifies the global memory block to be freed. 


The return value identifies the outcome of the function. It is NULL if the function is 
successful. Otherwise, it is equal to hMem. 


GlobalGetAtomName 4-240 


Comments The GlobalFree function must not be used to free a locked memory block, that is, a 
memory block with a lock count greater than zero. See the description of the GlobalFlags 
function for a list of the functions that affect the lock count. 

GlobalGetAtomName 

Syntax WORD GlobalGetAtomName(nAtom, IpBuffer, nSize) 


Return Value 


GlobalHandle 
Syntax 


Return Value 


This function retrieves a copy of the character string associated with the nAtom parameter 
and places it in the buffer pointed to by the /pBuffer parameter. The nSize parameter speci- 
fies the maximum size of the buffer. (A global atom is an atom that is available to all 
Windows applications.) 


Parameter Type/Description 

nAtom ATOM Identifies the character string to be retrieved. 

IpBuffer LPSTR Points to the buffer that is to receive the character string. 
nSize int Specifies the maximum size (in bytes) of the buffer. 


The return value specifies the actual number of bytes copied to the oe It is zero if the 
specified global atom is not valid. 


DWORD = GlobalHandle(wMem) 


This function retrieves the handle of the global memory object whose segment address or 
selector is specified by the wMem parameter. 


Parameter Type/Description 


wMem WORD _ Specifies an unsigned integer value that gives the segment 
address or See of a global memory object. 


The low-order word of the return value specifies the handle of the global memory object. 
The high-order word of the return value specifies the segment address or selector of the 
memory object. The return value is NULL if no handle exists for the memory object. 
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GlobalLock 


GlobalLock 
Syntax 


Return Value 


LPSTR _ GlobalLock(hMem) 


This function retrieves a pointer to the global memory block specified by the hMem para- 
meter. 


Except for nondiscardable objects in protected (standard or 386 enhanced) mode, the block 
is locked into memory at the given address and its lock count is increased by one. Locked 
memory is not subject to moving or discarding except when the memory block is being re- 
allocated by the GlobalReAlloc function. The block remains locked in memory until its 
lock count is decreased to zero. 


In protected mode, GlobalLock increments the lock count of discardable objects and auto- 
matic data segments only. 


Each time an application calls GlobalLock for an object, it must eventually call GlobalUn- 
lock for the object. The GlobalUnlock function decreases the lock count for the object if 
GlobalLock increased the lock count for the object. Other functions also can affect the 
lock count of a memory object. See the description of the GlobalFlags function for a list 

of the functions that affect the lock count. 


Parameter Type/Description 


hMem HANDLE Identifies the global memory block to be locked. 


The return value points to the first byte of memory in the global block if the function is 
successful. If the object has been discarded or an error occurs, the return value is NULL. 


Comments Discarded objects always have a lock count of zero. 
GlobalLRUNewest 
Syntax HANDLE GlobalLRUNewest(i:Mem) 


This function moves the global memory object identified by hMem to the newest least-re- 
cently-used (LRU) position in memory. This greatly reduces the likelihood that the object 
will be discarded soon, but does not prevent the object from eventually being discarded. 
Parameter Type/Description 


hMem HANDLE Identifies the global memory object to be moved. 
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Return Value The return value is NULL if the :Mem parameter does not specify a valid handle. 


Comments This function is useful only if hMem is discardable. 


GlobalLRUOlIdest 
Syntax HANDLE GlobalLRUOldest(h;Mem) 


This routine moves the global memory object identified by hMem to the oldest least-re- 
cently-used (LRU) position in memory and, in so doing, makes it the next candidate for 


discarding. 

Parameter Type/Description 

hMem HANDLE Identifies the global memory object to be moved. 
Return Value The return value is NULL if the hMem parameter does not specify a valid handle. 
Comments This function is useful only if hMem is discardable. 
GlobalNotify 
Syntax void GlobalNotify(/pNotifyProc) 

: This function installs a notification procedure for the current task. Windows calls the notifi- 
cation procedure whenever a global memory block allocated with the GMEM_NOTIFY 
flag is about to be discarded. 

Parameter Type/Description 
IpNotifyProc FARPROC Is the procedure instance address of the current task’s 
notification procedure. 
Return Value None. 
Comments An application must not call GlobalNotify more than once per instance. 


Windows does not call the notification procedure when it discards memory belonging to a 
DLL. 
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GlobalPageLock 


Callback Function 


If the object is discarded, the application must use the GMEM_NOTIFY flag when it recre- 
ates the object by calling the GlobalRealloc function. Otherwise, the application will not 
be notified when the object is discarded again. 


If the notification procedure returns a nonzero value, Windows discards the global memory 
block. If it returns zero, the block is not discarded. 


The callback function must use the Pascal calling convention and must be declared FAR. 
The callback function must reside in a fixed code segment of a DLL. 


BOOL FAR PASCAL NotifyProc(hMem) 

NotifyProc 1s a placeholder for the application-supplied function name. Export the name 
by including it in an EXPORTS statement in the DLL’s module-definition statement. 
Parameter Type/Description 


hMem HANDLE Identifies the global memory block being discarded. 


Return Value 


The function returns a nonzero value if Windows is to discard the memory block, and zero 
if it should not. 


Comments 


The callback function is not necessarily called in the context of the application that owns 
the routine. For this reason, the callback function should not assume the stack segment of 
the application. The callback function should not call any routine that might move memory. 


GlobalPageLock 


Syntax 


WORD = GlobalPageLock(wSelector) 


This function increments the page-lock count of the memory associated with the specified 
global selector. As long as its page-lock count is nonzero, the data which the selector 
references is guaranteed to remain in memory at the same physical address and to remain 
paged in. 


GlobalPageLock increments the page-lock count for the block of memory, and the 
GlobalPageUnlock function decrements the page-lock count. Page-locking operations can 
be nested, but each page lock must be balanced by a corresponding unlock. 
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Return Value 


‘Comments 


Parameter Type/Description 


wSelector WORD | Specifies the selector of the memory to be page-locked. 


The return value specifies the page-lock count after the function has incremented it. If the 
function fails, the return value is zero. 


An application should not use this function unless it is absolutely necessary. Use of this 
function violates preferred Windows programming practices. It is intended to be used for 
dynamically allocated data that must be accessed at interrupt time. For this reason, it must 
only be called from a DLL. 


GlobalPageUnlock 


Syntax 


Return Value 


GlobalReAlloc 
Syntax 


WORD = GlobalPageUnlock(wSelector) 


This function decrements the page-lock count for the block of memory identified by the 
wSelector parameter and, if the page-lock count reaches zero, allows the block of memory 
to move and to be paged to disk. 


The GlobalPageLock function increments the page-lock count for the block of memory, 
and GlobalPageUnlock decrements the page-lock count. Page-locking operations can be 
nested, but each page lock must be balanced by a corresponding unlock. 


Only libraries can call this function. 


Parameter Type/Description 


wSelector WORD Specifies the selector of the memory to be page-unlocked. 


The return value specifies the page-lock count after the function has decremented it. If the 
function fails, the return value is zero. 


HANDLE GlobalReAlloc(hMem, dwBytes, wF lags) 


This function reallocates the global memory block specified by the »Mem parameter by in- 
creasing or decreasing its size to the number of bytes specified by the dwBytes parameter. 
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GlobalReAlloc 


Parameter 


hMem 
dwBytes 
wFlags 


Type/Description 

HANDLE Identifies the global memory block to be reallocated. 
DWORD Specifies the new size of the memory block. 

WORD _ Specifies how to reallocate the global block. 


If the existing memory flags can be modified, use either one or both of 
the following flags (if both flags are specified, join them with the 
bitwise OR operator): 


Value Meaning 

GMEM_DISCARDABLE Memory can be discarded. Use only 
with GMEM_MODIFY. 

GMEM_MODIFY Memory flags are modified. The 


dwBytes parameter is ignored. Use 
only if an application will modify ex- 
isting memory flags and not 
reallocate the memory block to a 
new size. 


GMEM_MOVEABLE Memory is movable. If dwBytes is 
zero, this flag causes an object pre- 
viously allocated as moveable and 
discardable to be discarded if the 
block’s lock count is zero. If the 
block is not moveable and discard- 
able, the GlobalReAlloc will fail. If 
dwBytes is nonzero and the block 
specified by hMem is fixed, this flag 
allows the reallocated block to be 
moved to a new fixed location. If a 
moveable object is locked, this flag 
allows the object to be moved. This 
may occur even if the object is cur- 
rently locked by a previous call to 
GlobalLock. (Note that the handle 
returned by the GlobalReAlloc func- 
tion in this case may be different 
from the handle passed to the func- 
tion.) Use this flag with 
GMEM_MODIFY to make a fixed 
memory block moveable. 
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Parameter Type/Description 
Value Meaning 
GMEM_NOCOMPACT Memory will not be compacted or . 


discarded in order to satisfy the allo- 
cation request. This flag is ignored if 
the GMEM_MODIFY flag is set. 


GMEM_NODISCARD Objects will not be discarded in 
order to satisfy the allocation re- 
quest. This flag is ignored if the 
GMEM_MODIFY flag is set. 


GMEM_ZEROINIT If the block is growing, the addi- 
tional memory contents are 
initialized to zero. This flag is ig- 
nored if the GMEM_MODIFY flag 
is set. 


Return Value The return value identifies the reallocated global memory if the function is successful. The 
return value is NULL if the block cannot be reallocated. 


If the function is successful, the return value is always identical to the hMem parameter, un- 
less any of the following conditions is true: 


m The GMEM_MOVEABLE flag is used to allow movement of a fixed block to a new 
fixed location. 


= Windows is running in standard mode and the object is reallocated past a multiple of 
65,519 bytes (17 bytes less than 64K). 


= Windows is running in 386 enhanced mode and the object is reallocated past a multiple 
of 64K. 


GlobalSize 
Syntax DWORD  GlobalSize(hMem) 


This function retrieves the current size (in bytes) of the global memory block specified by 
the hMem parameter. 


Parameter Type/Description 


hMem HANDLE Identifies the global memory block. 
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GlobalUntix 


Return Value 


Comments 


The return value specifies the actual size (in bytes) of the specified memory block. It is 
zero if the given handle is not valid or if the object has been discarded. 


The actual size of a memory block is sometimes larger than the size requested when th 
memory was allocated. 


An application should call the GlobalFlags function prior to calling the GlobalSize func- 
tion in order to verify that the specified memory block was not discarded. If the memory 
block were discarded, the return value for GlobalSize would be meaningless. 


GlobalUnfix 


Syntax 


Return Value 


GlobalUnlock 
Syntax 


BOOL = GlobalUnfix(iMem) 
This function unlocks the global memory block specified by the hMem parameter. 


GlobalUnfix decreases the block’s lock count by one. The block is completely unlocked 
and subject to moving or discarding if the lock count is decreased to zero. Other functions 
also can affect the lock count of a memory object. See the description of the GlobalFlags 
function for a list of the functions that affect the lock count. 


Each time an application calls GlobalFix for an object, it must eventually call GlobalUn- 
fix for the object. 
Parameter Type/Description 


hMem HANDLE Identifies the global memory block to be unlocked. 


The return value specifies the outcome of the function. It is zero if the block’s lock count 
was decreased to zero. Otherwise, the return value is nonzero. 


BOOL = GlobalUnlock(iMem) 
This function unlocks the global memory block specified by the hMem parameter. 


In real mode, or if the block is discardable, GlobalUnlock decreases the block’s lock count 
by one. In protected mode, GlobalUnock decreases the lock count of discardable objects 
and automatic data segments only. 


The block is completely unlocked and subject to moving or discarding if the lock count is 
decreased to zero. Other functions also can affect the lock count of a memory object. See 
the description of the GlobalFlags function for a list of the functions that affect the lock 
count. 
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Return Value 


GlobalUnWire 
Syntax 


guaran 


Return Value 


GlobalWire 
Syntax 


In all cases, each time an application calls GlobalLock for an object, it must eventually 
call GlobalUnlock for the object. 


Parameter Type/Description 


hMem HANDLE Identifies the global memory block to be unlocked. 


The return value specifies the outcome of the function. It is zero if the block’s lock count 
was decreased to zero. Otherwise, the return value is nonzero. An application should not 
rely on the return value to determine the number of times it must subsequently call 
GlobalUnlock for the memory block. 


BOOL GlobalUnWire(iMem) 


This function unlocks a memory segment that was locked by the Global Wire function and 
decreases the lock count by one. 


The block is completely unlocked and subject to moving or discarding if the lock count is 
decreased to zero. Other functions also can affect the lock count of a memory object. See 
the description of the GlobalFlags function for a list of the functions that affect the lock 
count. 


Each time an application calls GlobalWire for an object, it must eventually call GlobalUn- 
Wire for the object. 
Parameter Type/Description 


hMem HANDLE Identifies the segment that will be unlocked. 
g 


The return value specifies the outcome of the function. It is TRUE if the memory segment 
was unlocked, that is, its lock count was decreased to zero. Otherwise, it is FALSE. 


LPSTR GlobalWire(i:Mem) 


This function moves a segment into low memory and locks it—a procedure that is ex- 
tremely useful if an application must lock a segment for a long period of time. If a segment 
from the middle portion of memory is locked for a long period of time, it causes memory- 
management problems by reducing the size of the largest, contiguous available block of 
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memory. The GlobalWire function moves a segment to the lowest possible address in 
memory and locks it, thereby freeing the memory area Windows uses most often. 


Each time an application calls GlobalWire for an object, it must eventually call GlobalUn- 
Wire for the object. The GlobalUnWire function decreases the lock count for the object. 
Other functions also can affect the lock count of a memory object. See the description of 
the GlobalFlags function for a list of the functions that affect the lock count. 


An application must not call the GlobalUnlock function to unlock the object. 


Parameter Type/Description 
hMem HANDLE Identifies the segment that will be moved and locked. 
Return Value The return value points to the new segment location. It is NULL if the function failed. 
GrayString 
Syntax BOOL  GrayString(iDC, hBrush, lpOutputFunc, lpData, nCount, X, Y, nWidth, Ex 
nHeight) fs 
This function draws gray text at the given location. The GrayString function draws gray c 


text by writing the text ina memory bitmap, graying the bitmap, and then copying the bit- 
map to the display. The function grays the text regardless of the selected brush and back- 
ground. GrayString uses the font currently selected for the device context specified by the 
hDC parameter. 


If the /pOutputFunc parameter is NULL, GDI uses the TextOut function, and the /pData 
parameter is assumed to be a long pointer to the character string to be output. If the 
characters to be output cannot be handled by TextOut (for example, the ae is stored as 
a bitmap), the application must supply its own output function. 


_ Parameter Type/Description 
hDC HDC Identifies the device context. 
hBrush HBRUSH Identifies the brush to be used for graying. 
IpOutputFunc FARPROC Is the procedure-instance address of the applica- 


tion-supplied function that will draw the string, or, if the 
TextOut function is to be used to draw the string, it is a NULL 
pointer. See the following “Comments” section for details. 


IpData DWORD _ Specifies a long pointer to data to be passed to the 
output function. If the /pOutputFunc parameter is NULL, [pData 
must be a long pointer to the string to be output. 


— GrayString 
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Return Value 


Comments 


Callback Function 


Parameter Type/Description 


nCount int Specifies the number of characters to be output. If the 
nCount parameter is zero, GrayString calculates the length of 
the string (assuming that /pData is a pointer to the string). If 
nCount is -1 and the function pointed to by IpOutputF unc re- 
turns zero, the image is shown but not grayed. 


xX int Specifies the logical x-coordinate of the starting position 
of the rectangle that encloses the string. 


Y int Specifies the logical y-coordinate of the starting position 
of the rectangle that encloses the string. 


nWidth int Specifies the width (in logical units) of the rectangle that 
encloses the string. If the nWidth parameter is zero, GrayString | 
calculates the width of the area, assuming /pDaia is a pointer to 
the string. 


nHeight int Specifies the height (in logical units) of the rectangle that 
encloses the string. If the nHeight parameter is zero, Gray- 
String calculates the height of the area, assuming /pData is a 
pointer to the string. 


The return value specifies the outcome of the function. It is nonzero if the string is drawn. 
A return value of zero means that either the TextOut function or the application-supplied 
output function returned zero, or there was insufficient memory to create a memory bitmap 
for graying. 


An application can draw grayed strings on devices that support a solid gray color, without 
calling the GrayString function. The system color COLOR_GRAYTEXT is the solid-gray 
system color used to draw disabled text. The application can call the GetSysColor func- 
tion to retrieve the color value of COLOR_GRAYTEXT. If the color is other than zero 
(black), the application can call the SetTextColor to set the text color to the color value 
and then draw the string directly. If the retrieved color is black, the application must call 
GrayString to gray the text. 


The callback function must use the Pascal calling convention and must be declared FAR. 


BOOL FAR PASCAL OutputFunc(hDC, IpData, nCount) 
HDC hDC; 

DWORD [pData; 

int nCount; 
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GrayString 


OutputF unc is a placeholder for the application-supplied callback function name. The ac- 
tual name must be exported by including it in an EXPORTS statement in the application’s 
module-definition file. 


Parameter Description 

hDC Identifies a memory device context with a bitmap of at least the 
width and height specified by the nWidth and nHeight parameters, re- 
spectively. 

lpData Points to the character string to be drawn. 

nCount Specifies the number of characters to be output. 


Return Value 


The return value must be nonzero to indicate success. Otherwise, it is zero. 


Comments 


This output function (OutputFunc) must draw an image relative to the coordinates (0,0) 
rather than (X,Y). The address passed as the JpOutputFunc parameter must be created by 
using the MakeProcInstance function, and the output function name must be exported; it 
must be explicitly defined in an EXPORTS statement of the application’s module-defini- 
tion file. 


The MM_TEXT mapping mode must be selected before using this function. 


HIBYTE 
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HIBYTE 
Syntax 


Return Value 


HideCaret 
Syntax 


Return Value 


BYTE HIBYTE(“/nteger) 

This macro retrieves the high-order byte from the integer value specified by the n/nteger 
parameter. 

Parameter Type/Description 


nInteger int Specifies the value to be converted. 


The return value specifies the high-order byte of the given value. 


void HideCaret(hWnda) 


This function hides the caret by removing it from the display screen. Although the caret is 
no longer visible, it can be displayed again by using the ShowCaret function. Hiding the 
caret does not destroy its current shape. 


The HideCaret function hides the caret only if the given window owns the caret. If the 
hWnd parameter is NULL, the function hides the caret only if a window in the current task 
owns the caret. 


Hiding is cumulative. If HideCaret has been called five times in a row, ShowCaret must 
be called five times before the caret will be shown. 
Parameter Type/Description 


hWnd HWND Identifies the window that owns the caret, or it is NULL to 
indirectly specify the window in the current task that owns the caret. 


None. 
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HiliteMenultem 


HiliteMenultem 


Syntax 


Return Value 


Comments 


BOOL  HiliteMenultem(iWnd, hMenu, w!DHiliteltem, wHilite) 


This function highlights or removes the highlighting from a top-level (menu-bar) menu 
item. : 


Parameter Type/Description 

hWnd HWND Identifies the window that contains the menu. 

hMenu HMENU Identifies the top-level menu that contains the item to 
be highlighted. 

wIDHiliteltem WORD _ Specifies the integer identifier of the menu item or the 


offset of the menu item in the menu, depending on the value of the 
wHilite parameter. 


wHilite WORD _ Specifies whether the menu item is highlighted or the 
highlight is removed. It can be a combination of MF_HILITE or 
MF_UNHILITE with MF_BYCOMMAND or MF_BYPOSI- 
TION. The values can be combined using the bitwise OR operator. 
These values have the following meanings: 


Value Meaning 

MF_BYCOMMAND Interprets w/DHiliteltem as the 
menu-item ID (the default inter- 
pretation). 

MF_BYPOSITION Interprets w/DHiliteltem as an off- 
set. 

MF_HILITE Highlights the item. If this value is 


not given, highlighting is removed 
from the item. 


MF_UNHILITE Removes highlighting from the 
item. 


The return value specifies whether or not the menu item is highlighted the outcome of the 
function. It is nonzero if the item is highlightedwas set to the specified highlight state. 
Otherwise, it is zero FALSE. 


The MF_HILITE and MF_UNHILITE flags can be used only with the HiliteMenultem 
function; they cannot be used with the ModifyMenu function. 


HIWORD 


4-254 
HIWORD 
Syntax WORD HIWORD(dwinteger) 
This macro retrieves the high-order word from the 32-bit integer value specified by the 
dwInteger parameter. 
Parameter Type/Description 
dwInteger DWORD _ Specifies the value to be converted. 


Return Value The return value specifies the high-order word of the given 32-bit integer value. 
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InflateRect 
Syntax 


Return Value 


Comments 


InitAtomTable 
Syntax 


Return Value 


une 


void InflateRect(/pRect, X, Y) 


This function increases or decreases the width and height of the specified rectangle. The 
InflateRect function adds X units to the left and right ends of the rectangle, and adds Y 
units to the top and bottom. The X and Y parameters are signed values; positive values in- 
crease the width and height, and negative values decrease them. 


Parameter Type/Description 
IpRect LPRECT Points to the RECT data structure to be modified. 
X int Specifies the amount to increase or decrease the rectangle 


width. It must be negative to decrease the width. 


Y int Specifies the amount to increase or decrease the rectangle 
height. It must be negative to decrease the height. 


None. 


The coordinate values of a rectangle must not be greater than 32,767 units or less than 
—32,768 units. The X and Y parameters must be chosen carefully to prevent invalid 
rectangles. 


BOOL = InitAtomTable(nSize) 


This function initializes an atom hash table and sets its size to that specified by the nSize 
parameter. If this function is not called, the atom hash table size is set to 37 by default. 


If used, this function should be called before any other atom-management function. 


Parameter Type/Description 


nSize int Specifies the size (in table entries) of the atom hash table. This 
value should be a prime number. 


The return value specifies the outcome of the function. It is nonzero if the function is 
successful. Otherwise, it is zero. 
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Comments If an application uses a large number of atoms, it can reduce the time required to add an 
atom to the atom table or to find an atom in the table by increasing the size of the table. 
However, this increases the amount of memory required to maintain the table. 
The size of the global atom table cannot be changed from its default size of 37. 

InSendMessage 

Syntax BOOL = InSendMessage( ) 


Return Value 


Comments 


This function specifies whether the current window function is processing a message that 
is passed to it through a call to the SendMessage function. 


This function has no parameters. 


The return value specifies the outcome of the function. It is TRUE if the window function 
is processing a message sent to it with SendMessage. Otherwise, it is FALSE. 


Applications use the InSendMessage function to determine how to handle errors that 
occur when an inactive window processes messages. For example, if the active window 
uses SendMessage to send a request for information to another window, the other window 
cannot become active until it returns control from the SendMessage call. The only method 
an inactive window has to inform the user of an error is to create a message box. 


InsertMenu 


Syntax 


BOOL _InsertMenu(hiMenu, nPosition, wFlags, wIDNewlItem, IlpNewlItem) 


This function inserts a new menu item at the position specified by the nPosition parameter, 
moving other items down the menu. The application can specify the state of the menu item 
by setting values in the wFlags parameter. 


Parameter | Type/Description 
hMenu HMENU Identifies the menu to be changed. 
nPosition WORD _ Specifies the menu item before which the new menu 


item is to be inserted. The interpretation of the nPosition parameter 
depends upon the setting of the wF/ags parameter. 
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InsertMenu 


Return Value 


Comments 


Parameter Type/Description 
If wFlags is: nPosition: 
MF_BYPOSITION Specifies the position of the ex- 
_ isting menu item. The first item in 
the menu is at position zero. 
If nPosition is —1, the new menu 
item is appended to the end of the 
menu. 
MF_BYCOMMAND Specifies the command ID of the ex- 
isting menu item. 
wFlags WORD _ Specifies how the nPosition parameter is interpreted 


and information about the state of the new menu item when it is 
added to the menu. It consists of one or more values listed in the 
following “Comments” section. 


wlDNewlItem WORD _ Specifies either the command ID of the new menu item 
or, if wFlags is set to MF_POPUP, the menu handle of the pop-up 
menu. 

IpNewltem LPSTR Specifies the content of the new menu item. If wFlags is 


set to MF_STRING (the default), then /pNewltem is a long pointer 
to a null-terminated character string. If wFlags is set to MF_BIT- 
MAP instead, then /pNew/tem contains a bitmap handle 
(HBITMAP) in its low-order word. If wFlags is set to 
MF_OWNERDRAW, /pNewItem specifies an application-supplied — 
32-bit value which the application can use to maintain additional 
data associated with the menu item. This 32-bit value is available 

to the application in the itemData field of the data structure 

pointed to by the /Param parameter of the following messages: 


WM_MEASUREITEM 
_WM_DRAWITEM 


These messages are sent when the menu item is initially displayed, 
or is changed. 


The return value specifies the outcome of the function. It is TRUE if the function is 
successful. Otherwise, it is FALSE. 


Whenever a menu changes (whether or not the menu resides in a window that is dis- 
played), the application should call DrawMenuBar. 
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Each of the following groups lists flags that should not be used together: 


= MF_BYCOMMAND and MF_BYPOSITION 

= MF DISABLED, MF_ENABLED, and MF_GRAYED 

= MF BITMAP, MF_STRING, MF_OWNERDRAW, and MF_SEPARATOR 
= MF _MENUBARBREAK and MF_ MENUBREAK 

= =MF_CHECKED and MF_UNCHECKED 


The following list describes the flags which may be set in the wFlags parameter: 


Value | Meaning 

MF_BITMAP Uses a bitmap as the item. The low-order word of the 
lpNewItem parameter contains the handle of the bitmap. 

MF_BYCOMMAND Specifies that the nPosition parameter gives the menu- 
item control ID number (default). | 

MF_BYPOSITION Specifies that the nPosition parameter gives the position 
of the menu item to be changed rather than an ID num- 
ber. 

MF_CHECKED Places a checkmark next to the menu item. If the applica- 


tion has supplied checkmark bitmaps (see the 
SetMenultemBitmaps function), setting this flag dis- 
plays the “checkmark on” bitmap next to the menu item. 


MF_DISABLED _ Disables the menu item so that it cannot be selected, but 
does not gray it. 

MF_ENABLED Enables the menu item so that it can be selected and re- 
stores it from its grayed state. 

MF_GRAYED Disables the menu item so that it cannot be selected and 
grays it. 


MF_MENUBARBREAK Same as MF_MENUBREAK except that for pop-up 
menus, separates the new column from the old column 
with a vertical line. 


MF_MENUBREAK Places the menu item on a new line for static menu-bar 
items. For pop-up menus, places the menu item in a new 
column, with no dividing line between the columns. 
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IntersectClipRect 


Value Meaning 


MF_OWNERDRAW Specifies that the item is an owner-draw item. The 
window that owns the menu receives a 
WM_MEASUREITEM message when the menu is dis- 
played for the first time to retrieve the height and width 
of the menu item. The WM_DRAWITEM message is 
then sent to the owner whenever the owner must update 
the visual appearance of the menu item. This option is 
not valid for a top-level menu item. 


MF_POPUP Specifies that the menu item has a pop-up menu as- 
sociated with it. The w/DNew/tem parameter specifies a 
handle to a pop-up menu to be associated with the item. 
Use the MF_OWNERDRAW flag to add either a top- 
level pop-up menu or a hierarchical pop-up menu to a 
pop-up menu item. 


MF_SEPARATOR Draws a horizontal dividing line. You can use this flag in 
a pop-up menu. This line cannot be grayed, disabled, or 
highlighted. Windows ignores the pNewItem and wID- 
Newltem parameters. 


MF_STRING Specifies that the menu item is a character string; the 
IpNewItem parameter points to the string for the item. 


MF_UNCHECKED Does not place a checkmark next to the item (default). If 
the application has supplied checkmark bitmaps (see Set- 
MenultemBitmaps), setting this flag displays the 
“checkmark off’ bitmap next to the menu item. 


IntersectClipRect 


Syntax 


int IntersectClipRect(ADC, X1, Y1, X2, Y2) 


This function creates a new clipping region by forming the intersection of the current re- 
gion and the rectangle specified by X/, YJ, X2, and Y2. GDI clips all subsequent output to 
fit within the new boundary. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
X1 int Specifies the logical x-coordinate of the upper-left corner of the 


rectangle. 
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Parameter Type/Description 

Y/ int Specifies the logical y-coordinate of the upper-left corner of the 
rectangle. 

X2 int Specifies the logical x-coordinate of the lower-right corner of 


the rectangle. 


Y2 int Specifies the logical y-coordinate of the lower-right corner of 
the rectangle. 


Return Value The return value specifies the new clipping region’s type. It can be any one of the follow- 


ing values: 
Value Meaning 


COMPLEXREGION New clipping region has overlapping borders. 


ERROR Device context is not valid. 
NULLREGION New clipping region is empty. 
SIMPLEREGION New clipping region has no overlapping borders. 
Comments The width of the rectangle, specified by the absolute value of X2 — X/, must not exceed 
j 32,767 units. This limit applies to the height of the rectangle as well. 
ol 
Te 
=. 
— IntersectRect 
Syntax int IntersectRect(/pDestRect, lpSrcl Rect, lpSrc2Rect) 


This function creates the intersection of two existing rectangles. The intersection is the 
largest rectangle contained in both rectangles. The IntersectRect function copies the new 
rectangle to the RECT data structure pointed to by the JpDestRect parameter. 


Parameter Type/Description 
. lpDestRect LPRECT Points to the RECT data structure that is to receive the 
intersection. 
IpSrcl Rect LPRECT © Points to a RECT data structure that contains a source 
rectangle. 
IpSrc2Rect LPRECT Points to a RECT data structure that contains a source 


rectangle. 
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InvalidateRect 


Return Value 


invalidateRect 
Syntax 


Return Value 


Comments 


InvalidateRgn 
Syntax 


The return value specifies the intersection of two rectangles. It is nonzero if the 
intersection of the two rectangles is not empty. It is zero if the intersection is empty. 


void InvalidateRect(hWnd, IpRect, bErase) 


This function invalidates the client area within the given rectangle by adding that rectangle 
to the window’s update region. The invalidated rectangle, along with all other areas in the 
update region, is marked for painting when the next WM_PAINT message occurs. The 
invalidated areas accumulate in the update region until the region is processed when the 
next WM_PAINT message occurs, or the region is validated by using the ValidateRect or 
ValidateRgn function. 


The bErase parameter specifies whether the background within the update area is to be 
erased when the update region is processed. If bErase is nonzero, the background is erased 
when the BeginPaint function is called; if bErase is zero, the background remains un- 
changed. If bErase is nonzero for any part of the update region, the background in the en- 
tire region is erased, not just in the given part. 


Parameter Type/Description 

hWnd HWND Identifies the window whose update region is to be mod- 
ified. 

IpRect LPRECT Points to a RECT data structure that contains the 


rectangle (in client coordinates) to be added to the update region. If 
the /pRect parameter is NULL, the entire client area is added to the 
region. 


bErase BOOL Specifies whether the background within the update region 
is to be erased. 


None. 


Windows sends a WM_PAINT message to a window whenever its update region is not 
empty and there are no other messages in the application queue for that window. 


void InvalidateRgn(iWnd, hRgn, bErase) 


This function invalidates the client area within the given region by adding it to the current 
update region of the given window. The invalidated region, along with all other areas in 
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the update region, is marked for painting when the next WM_PAINT message occurs. The 
invalidated areas accumulate in the update region until the region is processed when the 
next WM_PAINT message occurs, or the region is validated by using the ValidateRect or 
ValidateRgn function. 


The bErase parameter specifies whether the background within the update area is to be 
erased when the update region is processed. If bErase is nonzero, the background is erased 
when the BeginPaint function is called; if bErase is zero, the background remains un- 
changed. If bErase is nonzero for any part of the update region, Se background in the en- 
tire region is erased, not just in the given part. 


Parameter Type/Description 

hWnd HWND Identifies the window whose update region is to be mod- 
ified. 

hRgn HRGN Identifies the region to be added to the update region. The 


region is assumed to have client coordinates. 


bErase BOOL _ Specifies whether the background within the update region 
is to be erased. 


Return Value None. 


«. Gomments Windows sends a WM_PAINT message to a window whenever its update region is not 
So empty and there are no other messages in the application queue for that window. 


1 | The given region must have been previously created by using one of the region functions 
c (for more information, see Chapter 1, “Window Manager Interface Functions’). 


InvertRect 
Syntax void InvertRect(hDC, IpRect) 


This function inverts the contents of the given rectangle. On monochrome displays, the In- 
vertRect function makes white pixels black, and black pixels white. On color displays, the 
inversion depends on how colors are generated for the display. Calling InvertRect twice 
with the same rectangle restores the display to its previous colors. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpRect LPRECT © Points to a RECT data structure that contains the logi- 


cal coordinates of the rectangle to be inverted. 


4-263 InvertRgn 


Return Value None. 


Comments The InvertRect function compares the values of the top, bottom, left, and right fields of 


the specified rectangle. If bottom is less than or equal to top, or if right is less than or 
equal to left, the rectangle is not drawn. 


InvertRgn 
Syntax BOOL = InvertRgn(hDC, hRgn) 


This function inverts the colors in the region specified by the hRgn parameter. On mono- 
chrome displays, the InvertRgn function makes white pixels black, and black pixels 
white. On color displays, the inversion depends on how the colors are generated for the dis- 


play. 

Parameter Type/Description 

hDC HDC Identifies the device context for the region. 

hRgn HRGN Identifies the region to be filled. The coordinates for the re- 


gion are specified in device units. 


Return Value The return value specifies the outcome of the function. It is nonzero if the function is 


successful. Otherwise, it is zero. 


IsCharAlpha 
Syntax BOOL = IsCharAlpha(cChar) 


This function determines whether a character is an alphabetical character. This determina- 


tion is made by the language driver based on the criteria of the current language selected 
by the user at setup or with the Control Panel. 


Parameter Type/Description 


cChar char Specifies the character to be tested. 


Return Value The return value is TRUE if the character is alphabetical. Otherwise, it is FALSE. 


LT ees 


IsCharAlphaNumeric 4-264 


IsCharAlphaNumeric 


Syntax 


Return Value 


IsCharLower 


Syntax 


: Return Value 


BOOL = IsCharAlphaNumeric(cChar) 


This function determines whether a character is an alphabetical or numerical character. 
This determination is made by the language driver based on the criteria of the current lan- 
guage selected by the user at setup or with the Control Panel. 


Parameter Type/Description 


cChar char Specifies the character to be tested. 


The return value is TRUE if the character is an alphanumeric character. Otherwise, it is 
FALSE. 


BOOL  IsCharLower(cChar) 
This function determines whether a character is a lowercase character. This determination 


is made by the language driver based on the criteria of the current language selected by the 
user at setup or with the Control Panel. 


Parameter Type/Description 


cChar char Specifies the character to be tested. 


The return value is TRUE if the character is lowercase. Otherwise, it is FALSE. 


IsCharUpper 


Syntax 


BOOL = IsCharUpper(cChar) 


This function determines whether a character is an uppercase character. This determination 
is made by the language driver based on the criteria of the current language selected by the 
user at setup or with the Control Panel. 


Parameter Type/Description 


cChar char Specifies the character to be tested. 
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Return Value The return value is TRUE if the character is uppercase. Otherwise, it is FALSE. 
IsChild 
Syntax BOOL = IsChild(:WndParent, hWnd) 


This function indicates whether the window specified by the hWnd parameter is a child 
window or other direct descendant of the window specified by the hWndParent parameter. 
A child window is the direct descendant of a given parent window if that parent window is 
in the chain of parent windows that leads from the original pop-up window to the child 
window. 


Parameter Type/Description 
hWndParent HWND Identifies a window. 
hWnd HWND Identifies the window to be checked. 


Return Value The return value specifies the outcome of the function. It is TRUE if the window identified 
by the hWnd parameter is a child window of the window identified by the hWndParent par- 
ameter. Otherwise, it is FALSE. 


IsClipboardFormatAvailable 
Syntax BOOL = IsClipboardFormatAvailable(wFormat) 


This function specifies whether data of a certain type exist in the clipboard. 


Parameter Type/Description 


wFormat WORD _ Specifies a registered clipboard format. For information 
on clipboard formats, see the description of the SetClipboardData 
function, later in this chapter. 


Return Value The return value specifies the outcome of the function. It is TRUE if data having the 
specified format are present. Otherwise, it is FALSE. 


Comments This function is typically called during processing of the WM_INITMENU or WM_INIT- 
MENUPOPUP message to determine whether the clipboard contains data that the applica- 
tion can paste. If such data are present, the application typically enables the Paste 
command (in its Edit menu). 
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isDialogMessage 


Syntax 


Return Value 


BOOL = IsDialogMessage(iD/g, [pMsg) 


This function determines whether the given message is intended for the modeless dialog 
box specified by the hD/g parameter, and automatically processes the message if it is. 
When the IsDialogMessage function processes a message, it checks for keyboard mes- 
sages and converts them into selection commands for the corresponding dialog box. For ex- 
ample, the TAB key selects the next control or group of controls, and the DOWN key selects 
the next control in a group. 


If a message is processed by IsDialogMessage, it must not be passed to the Translate- 
Message or DispatchMessage function. This is because IsDialogMessage performs all 
necessary translating and dispatching of messages. 


IsDialogMessage sends WM_GETDLGCODE messages to the dialog function to deter- 
mine which keys should be processed. 


Parameter Type/Description 
hDlg HWND Identifies the dialog box. 
IpMsg LPMSG Points to an MSG data structure that contains the 


message to be checked. 


The return value specifies whether or not the given message has been processed. It is non- 
zero if the message has been processed. Otherwise, it is zero. 


Comments Although IsDialogMessage is intended for modeless dialog boxes, it can be used with any 
window that contains controls to provide the same keyboard selection as in a dialog box. 

IsDIigButtonChecked 

Syntax WORD _IsDigButtonChecked(hD/g, n/DButton) 


This function determines whether a button control has a checkmark next to it, and whether 
a three-state button control is grayed, checked, or neither. The IsDlgButtonChecked func- 
tion sends a BM_GETCHECK message to the button control. 
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Islconic 


Return Value 


Islconic 
Syntax 


Return Value 


IsRectEmpty 
Syntax 


Return Value 


Parameter Type/Description 
hDlig HWND Identifies the dialog box that contains the button control. 
nIDButton int Specifies the integer identifier of the button control. 


The return value specifies the outcome of the function. It is nonzero if the given control 
has a checkmark next to it. Otherwise, it is zero. For three-state buttons, the return value is 
2 if the button is grayed, 1 if the button has a checkmark next to it, and zero otherwise. 


BOOL _IsIconic(hWnd) 


This function specifies whether a window is minimized (iconic). 


Parameter Type/Description 


hWnd HWND Identifies the window. 


The return value specifies whether the window is minimized. It is nonzero if the window is 
minimized. Otherwise, it is zero. 


BOOL = IsRectEmpty(/pRect) 

This function determines whether or not the specified rectangle is empty. A rectangle is 
empty if the width and/or height are zero. 

Parameter Type/Description 


lpRect LPRECT Points to a RECT data structure that contains the 
specified rectangle. 


The return value specifies whether or not the given rectangle is empty. It is nonzero if the 
rectangle is empty. It is zero if the rectangle is not empty. 
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IsWindow | 
Syntax BOOL = IsWindow(hWnd) 


This function determines whether the window identified by the hWnd parameter is a valid, 
existing window. 


Parameter Type/Description 


hWnd HWND Identifies the window. 


Return Value The return value specifies whether or not the given window is valid. It is nonzero if hWnd 
is a valid window. Otherwise, it is zero. 


IsWindowEnabled 
Syntax BOOL IsWindowEnabled(hWna) 


This function specifies whether the specified window is enabled for mouse and keyboard 
input. 


Parameter Type/Description 


hWnd HWND Identifies the window. 


Return Value —_—-—« The return value specifies whether or not the given window is enabled. It is nonzero if the 
window is enabled. Otherwise, it is zero. 


Comments A child window receives input only if it is both enabled and visible. 
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IsWindowVisible 
Syntax BOOL = IsWindowVisible(iWna) 


Return Value 


IsZoomed 
Syntax 


Return Value 


The IsWindow Visible function returns nonzero anytime an application has made a 
window visible by using the ShowWindow function (even if the specified window is 
completely covered by another child or pop-up window, the return value is nonzero). 


Parameter Type/Description 


hWnd HWND Identifies the window. 


The return value specifies whether or not a given window exists on the screen. It is non- 
zero if the given window exists on the screen. Otherwise, it is zero. 


BOOL = IsZoomed(hWnd) 


This function determines whether or not a window has been maximized. 


Parameter Type/Description 


hWnd HWND Identifies the window. 


The return value specifies whether or not the given window is maximized. It is nonzero if 
the window is maximized. Otherwise, it is zero. 
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KillTimer 
Syntax BOOL = KillTimer(iWnd, nIDEvent) 
This function kills the timer event identified by the hWnd and nIDEvent parameters. Any 
pending WM_TIMER messages associated with the timer are removed from the message 
queue. 
Parameter Type/Description 
hWnd HWND Identifies the window associated with the given timer 
event. This must be the same value passed as the hWnd parameter to 
the SetTimer function call that created the timer event. 
nIDEvent int Specifies the timer event to be killed. If the application called 
SetTimer with the hWnd parameter set to NULL, this must be the 
event identifier returned by SetTimer. If the hWnd parameter of Set- 
Timer was a valid window handle, n/DEvent must be the value of 
the nIDEvent parameter passed to SetTimer. 
Return Value The return value specifies the outcome of the function. It is nonzero if the event was killed. 


It is zero if the KillTimer function could not find the specified timer event. 


nn 
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_Iclose 


_Iclose 
Syntax 


Return Value 


_Icreat 
Syntax 


int Iclose(iFile) 


This function closes the file specified by the iFile parameter. As a result, the file is no 
longer available for reading or writing. 


The File argument is returned by the call that created or last opened the file. 


Parameter Type/Description 


hFile int Specifies the MS-DOS file handle of the file to be closed. 


The return value indicates whether the function successfully closed the file. It is zero if the 
function closed the file, or —1 if the function failed. 


int Icreat(/pPathName, iAttribute) 


This function opens a file with the name specified by the [pPathName parameter. The 
iAttribute parameter specifies the attributes of the file when the function opens it. If the file 
does not exist, the function creates a new file and opens it,for writing. If the file does exist, 
the function truncates the file size to zero and opens it for reading and writing. When the 
function opens the file, the pointer is set to the beginning of the file. 


Parameter Type/Description 

lpPathName LPSTR Points to a null-terminated character string that names the 
file to be opened. The string must consist of characters from the 
ANSI character set. 

iAttribute int Specifies the file attributes. The parameter must be one of these 
values: 
Value Meaning 
0 Normal; can be read or written without restriction. 
1 Read-only; cannot be opened for write; a file with 


the same name cannot be created. 
2 Hidden; not found by directory search. 


3 System; not found by directory search. 
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Return Value The return value specifies an MS-DOS file handle if the function was successful. Other- 
wise, the return value is —1. 


LimitEmsPages 
Syntax void LimitEmsPages (dwKbytes) 


This function limits the amount of expanded memory that Windows will assign to an appli- 
cation. It does not limit the amount of expanded memory that the application can get by 
directly calling INT 67H. 


Parameter Type/Description 


dwK bytes DWORD _ Specifies the number of kilobytes of expanded memory 
to which the application is to have access. 


Return value None. 


Comments LimitEmsPages has an effect only if expanded memory is installed and being used by 
Windows. If Windows is not using expanded memory, then the function has no effect. 


LineDDA 
Syntax void LineDDA(X/, Y/, X2, Y2, IpLineFunc, lpData) 


This function computes all successive points in a line starting at the point specified by the 
X/ and Y/ parameters and ending at the point specified by the X2 and Y2 parameters. The 
endpoint is not included as part of the line. For each point on the line, the LineDDA func- 
tion calls the application-supplied function pointed to by the /pLineFunc parameter, pass- 
ing to the function the coordinates of the current point and the /pData parameter. 


_ Parameter Type/Description 
Xl int Specifies the logical x-coordinate of the first point. 
Yl int Specifies the logical y-coordinate of the first point. 
X2 int Specifies the logical x-coordinate of the endpoint. 
Y2 int Specifies the logical y-coordinate of the endpoint. 
IpLineFunc FARPROC Is the procedure-instance address of the application- 


supplied function. See the following “Comments” section for details. 
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LineTo 


Return Value 


Comments 


Callback Function 


LineTo 
Syntax 


Parameter Type/Description 
IpData LPSTR Points to the application-supplied data. 
None. 


The address passed by the JpLineFunc parameter must be created by using the Make- 
ProcInstance function. 


The callback function must use.the Pascal calling convention and must be declared FAR. 


void FAR PASCAL LineFunc(X, Y, lpData) 

int xX; 

int Y; 

LPSTR /[pData; 

LineF unc is a placeholder for the application-supplied function name. The actual name 


must be exported by including it in an EXPORTS statement in the application’s module- 
definition file. 


Parameter Definition 

x Specifies the x-coordinate of the current point. 
Y Specifies the y-coordinate of the current point. 
IpData Points to the application-supplied data. 


Return Value 


The function can perform any task. It has no return value. 


BOOL = LineTo(hDC, X, Y) 


This function draws a line from the current position up to, but not including, the point 
specified by the X and Y parameters. The line is drawn with the selected pen. If no error 
occurs, the position is set to (X,Y). 


Parameter Type/Description 


hDC HDC _Identifies the device context. 


_Ilseek 


Return Value 
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Parameter Type/Description 
X int Specifies the logical x-coordinate of the endpoint for the line. 
Y int Specifies the logical y-coordinate of the endpoint for the line. 


The return value specifies whether or not the line is drawn. It is nonzero if the line is 
drawn. Otherwise, it is zero. 


_Ilseek 
Syntax 


Return Value 


Comments 


LONG _lIlseek(hFile, lOffset, iOrigin) 


This function repositions the pointer in a previously opened file. The iOrigin parameter 
specifies the starting position in the file, and /Offset specifies how far (in bytes) the func- 
tion is to move the pointer. . 


Parameter Type/Description — 

hFile int Specifies the MS-DOS file handle of the file. 

lOffset LONG _ Specifies the number of bytes the pointer is to be moved. 
1Origin int Specifies the starting position and direction of the pointer. The 


parameter must be one of the following values: 


Value Meaning 

0 Move the file pointer /Offset bytes from the begin- 
ning of the file. 

1 Move the file pointer /Offset bytes from the cur- 
rent position of the file. 

2 Move the file pointer /Offset bytes from the end of 
the file. 


The return value specifies the new offset of the pointer (in bytes) from the beginning of the 
file. The return value is —1 if the function fails. 


When a file is initially opened, the file pointer is positioned at the beginning of the file. 
The _liseek function permits random access to a file’s contents by moving the pointer an 
arbitrary amount without reading data. 
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LoadAccelerators 
Syntax HANDLE = LoadAccelerators(h/nstance, lpTableName) 


This function loads the accelerator table named by the IpTableName parameter from the 
executable file associated with the module specified by the h/nstance parameter. 


The LoadAccelerators function loads the table only if it has not been previously loaded. 
Otherwise, it retrieves a handle to the loaded table. 


Parameter Type/Description 


hInstance HANDLE Identifies an instance of the module whose executable 
file contains the accelerator table. 


IpTableName LPSTR Points to a string that names the accelerator table. The 
' string must be a null-terminated character string. 


Return Value The return value identifies the loaded accelerator table if the function is successful. Other- 
wise, it is NULL. 


LoadBitmap 
Syntax HBITMAP LoadBitmap(h/nstance, IpBitmapName) 


This function loads the bitmap resource named by the /pBitmapName parameter from the 
executable file associated with the module specified by the h/nstance parameter. 


Parameter Type/Description 


hInstance HANDLE Identifies the instance of the module whose exe- 
cutable file contains the bitmap. 


IpBitmapName LPSTR Points to a character string that names the bitmap. The 
string must be a null-terminated character string. 


Return Value The return value identifies the specified bitmap. It is NULL if no such bitmap exists. 


Comments The application must call the DeleteObject function to delete each bitmap handle returned 


by the LoadBitmap function. This also applies to the predefined bitmaps described in the 
following paragraph. | 
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The LoadBitmap function can also be used to access the predefined bitmaps used 
by Windows. The //nstance parameter must be set to NULL, and the /pBitmapName 
parameter must be one of the following values: 


=» OBM_BTNCORNERS 
= OBM_BTSIZE 
=» OBM_CHECK 
=» OBM_CHECKBOXES 
=m OBM_CLOSE 
=» OBM_COMBO 
a OBM_DNARROW 
=» OBM_DNARROWD 
= OBM_LFARROW 
«a OBM_LFARROWD 
=» OBM_MNARROW 
ms OBM_OLD_CLOSE 
«» OBM_OLD_DNARROW 
= OBM_OLD_LFARROW 
a» OBM_OLD_REDUCE 
=» OBM_OLD_RESTORE 
=» OBM_OLD_RGARROW 
=» OBM_OLD_UPARROW 
a OBM_OLD_ZOOM 
=» OBM_REDUCE 
=» OBM_REDUCED 
= OBM_RESTORE 
_m@ OBM_RESTORED 
=» OBM_RGARROW 
a OBM_RGARROWD 
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LoadCursor 


LoadCursor 
Syntax 


Return Value 


Comments 


= OBM_SIZE 

= OBM_UPARROW 

m OBM_UPARROWD 

=» OBM_ZOOM 

=» OBM_ZOOMD 

oa names that begin OBM_OLD represent bitmaps used by Windows versions prior 
to 5.0. 


The /pBitmapName parameter can also be a value created by the MAKEINTRESOURCE 
macro. If it is, the ID must reside in the low-order word of [pBitmapName, and the high- 
order word must contain zeros. 


HCURSOR = LoadCursor(h/nstance, lpCursorName) 


This function loads the cursor resource named by the /pCursorName parameter from the 
executable file associated with the module specified by the hInstance parameter. The func- 
tion loads the cursor into memory only if it has not been previously loaded. Otherwise, it 
retrieves a handle to the existing resource. 


Parameter Type/Description 


hInstance HANDLE Identifies an instance of the module whose exe- 
cutable file contains the cursor. 


IpCursorName LPSTR Points to a character string that names the cursor 
resource. The string must be a null-terminated character string. 


The return value identifies the newly loaded cursor if the function is successful. Otherwise, 
it is NULL. 


The LoadCursor function returns a valid cursor handle only if the Jp>CursorName parame- 
ter identifies a cursor resource. If JpCursorName identifies any type of resource other than 
a cursor (such as an icon), the return value will not be NULL, even though it is not a valid 
cursor handle. 


Use the LoadCursor function to access the predefined cursors used by Windows. To do 
this, the hJnstance parameter must be set to NULL, and the JpCursorName parameter must 
be one of the following values: 


Loadlcon 


Loadicon 
Syntax 


Value 
IDC_ARROW 
IDC_CROSS 
IDC_IBEAM 
IDC_ICON 
IDC_SIZE 


IDC_SIZENESW 


IDC_SIZENS 
IDC_SIZENWSE 


IDC_SIZEWE 
IDC_UPARROW 
IDC_WAIT 
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Meaning 

Standard arrow cursor. 
Crosshair cursor. 

Text I-beam cursor. 
Empty icon. 


Loads a square with a smaller square inside its lower-right 
corner. 


Double-pointed cursor with arrows pointing northeast and 
southwest. 


Double-pointed cursor with arrows pointing north and south. 


Double-pointed cursor with arrows pointing northwest and 
southeast. 


Double-pointed cursor with arrows pointing west and east. 
Vertical arrow cursor. 


Hourglass cursor. 


The /pCursorName parameter can contain a value created by the MAKEINTRE- 
SOURCE macro. If it does, the ID must reside in the low-order word of IpCursorName, 
and the high-order word must be set to zero. 


HICON = LoadIcon(h/nstance, lplconName) 


This function loads the icon resource named by the /p/conName parameter from the exe- 
cutable file associated with the module specified by the h/nstance parameter. The function 
loads the icon only if it has not been previously loaded. Otherwise, it retrieves a handle to 
the loaded resource. 


Parameter 


hInstance 


IpIconName 


Type/Description 


HANDLE Identifies an instance of the module whose executable 
file contains the icon. 


LPSTR Points to a character string that names the icon resource. 
The string must be a null-terminated character string. 
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Return Value 


Comments 


LoadLibrary 
Syntax 


Return Value 


The return value identifies an icon resource if the function is successful. Otherwise, it is 
NULL. 


Use the LoadIcon function to access the predefined icons used by Windows. To do this, 
the AInstance parameter must be set to NULL, and the /p/conName parameter must be one 
of the following values: 


Value Meaning 

IDI_APPLICATION Default application icon. 

IDI_LASTERISK Asterisk (used in informative messages). 
IDI_EXCLAMATION Exclamation point (used in warning messages). 
IDI_HAND Hand-shaped icon (used in serious warning messages). 
IDI_QUESTION Question mark (used in prompting messages). 


The [pIconName parameter can also contain a value created by the MAKEINTRE- 
SOURCE macro. If it does, the ID must reside in the low-order word of I[p/conName, 
and the high-order word must be set to zero. 


HANDLE LoadLibrary(/pLibFileName) 


This function loads the library module contained in the specified file and retrieves a handle 
to the loaded module instance. 


Parameter Type/Description 


IpLibFileName LPSTR Points to a string that names the library file. The string 
must be a null-terminated character string. 


The return value identifies the instance of the loaded library module. Otherwise, it is a 
value less than 32 that specifies the error. The following list describes the error values 
returned by this function: 


Value Meaning 
0 Out of memory. 


2 File not found. 
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Value Meaning 

3 Path not found. 

5 Attempt to dynamically link to a task. 

6 Library requires separate data segments for each task. 

10 Incorrect Windows version. 

11 Invalid .EXE file (non-Windows .EXE or error in .EXE image). 

12 OS/2 application. 

a DOS 4.0 application. 

14 Unknown .EXE type. 

15 Attempt in protected (standard or 386 enhanced) mode to load an 
-EXE created for an earlier version of Windows. 

16 Attempt to load a second instance of an .EXE containing multiple, 
writeable data segments. 

17 Attempt in large-frame EMS mode to load a second instance of an 
application that links to certain nonshareable DLLs already in use. 

18 Attempt in real mode to load an application marked for protected 
mode only. 

= LoadMenu 
a Syntax HMENU  LoadMenu(hlnstance, IpMenuName) 


This function loads the menu resource named by the JpMenuName parameter from the exe- 
cutable file associated with the module specified by the hInstance parameter. 


Parameter Type/Description 


hInstance HANDLE Identifies an instance of the module whose exe- 
cutable file contains the menu. 


lpMenuName LPSTR Points to a character string that names the menu 
resource. The string must be a null-terminated character string. 


Return Value The return value identifies a menu resource if the function is successful. Otherwise, it is 
. NULL. 
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Comments The /pMenuName parameter can contain a value created by the MAKEINTRESOURCE 


macro. If it does, the ID must reside in the low-order word of JpMenuName, and the high- 
order word must be set to zero. 


LoadMenulndirect 
Syntax HMENU  LoadMenulndirect(/pMenuTemplate) 


This function loads into memory the menu named by the [pMenuTemplate parameter. The 
template specified by /pMenuTemplate is a header followed by a collection of one or more 
MENUITEMTEMPLATE structures, each of which may contain one or more menu 
items and pop-up menus. 


Parameter Type/Description 


lpMenuTemplate LPSTR Points to a menu template (which is a collection of 
one or more MENUITEMTEMPLATE structures). 


Return Value The return value identifies the menu if the function is successful. Otherwise, it is NULL. 


LoadModule 

Syntax HANDLE  LoadModule(/pModuleName, lpParameterBlock) 
This function loads and executes a Windows program or creates a new instance of an ex- 
isting Windows program. 
Parameter Type/Description 


IpModuleName LPSTR Points to a null-terminated string that contains 
the filename of the application to be run. If the 
IpModuleName string does not contain a directory path, 
Windows will search for the executable file in this order: 


1. The current directory 


2. The Windows directory (the directory containing 
WIN.COM); the GetWindowsDirectory function ob- 
tains the pathname of this directory 
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Parameter Type/Description 


3. The Windows system directory (the directory containing 
such system files as KERNEL.EXE); the GetSystem- 
Directory function obtains the pathname of this 
directory 


4. The directories listed in the PATH environment variable 
5. The list of directories mapped in a network 


If the application filename does not contain an extension, 
then .EXE is assumed. 


IpParameterBlock LPVOID Points to a data structure consisting of four 
fields that defines a parameter block. This data structure 
consists of the following fields: 


Field Type/Description 


wEnvSeg WORD Specifies the segment 
address of the environment under which 
the module is to run; 0 indicates that the 
Windows environment is to be copied. 


lpCmdLine LPSTR Points to a null-terminated 
character string that contains a correctly 
formed command line. This string must 
not exceed 120 bytes in length. 


IpCmdShow LPVOID Points to a data structure 
containing two WORD-length values. 
The first value must always be set to two. 
The second value specifies how the appli- 
cation window is to be shown. See the 
description of the nCmdShow paramter 
of the ShowWindow function for a list 
of the acceptable values. 


dwReserved DWORD Js reserved and must be 
NULL. 


All unused fields should be set to NULL, except for 
IpCmdLine, which must point to a null string if it is not 
used. 
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LoadResource 


Return Value 


Comments 


LoadResource 
Syntax 


The return value identifies the instance of the loaded module if the function was success- 
ful. Otherwise, it is a value less than 32 that specifies the error. The following list describes 
the error values returned by this function: 


Value Meaning 

0 ‘Out of memory. 

pi File not found. 

3 Path not found. 

5 Attempt to dynamically link to a task. 

6 Library requires separate data segments for each task. 

10 Incorrect Windows version. 

11 | Invalid .EXE file (Mon-Windows .EXE or error in .EXE image). 

12 OS/2 application. 

13 DOS 4.0 application. 

14 Unknown .EXE type. 

15 Attempt in protected (standard or 386 enhanced) mode to load an 
.EXE created for an earlier version of Windows. 

16 Attempt to load a second instance of an .EXE containing multiple, 
writeable data segments. 

17 Attempt in large-frame EMS mode to load a second instance of an 
application that links to certain nonshareable DLLs already in use. 

18 Attempt in real mode to load an application marked for protected 
mode only. 


The WinExec function provides an alternative method for executing a program. 


HANDLE  LoadResource(/nstance, hResInfo) 


This function loads a resource identified by the hResInfo parameter from the executable 
file associated with the module specified by the hJnstance parameter. The function loads 
the resource into memory only if it has not been previously loaded. Dienwise; it retrieves 
a handle to the existing resource. 
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Parameter Type/Description 

hInstance HANDLE Identifies an instance of the module whose executable 
file contains the resource. 

hResInfo HANDLE Identifies the desired resource. This handle is assumed 


to have been created by using the FindResource function. 


Return Value The return value identifies the global memory block to receive the data associated with the 
resource. It is NULL if no such resource exists. 


Comments The resource is not actually loaded until the LockResource function is called to translate 
the handle returned by LoadResource into a far pointer to the resource data. 


LoadString 
Syntax int LoadString(h/nstance, wID, lpBuffer, nBufferMax) 
This function loads a string resource identified by the w/D parameter from the executable 
file associated with the module specified by the h/nstance parameter. The function copies 
the string into the buffer pointed to by the /pBuffer parameter, and appends a terminating 
null character. 
Parameter Type/Description 
hInstance HANDLE Identifies an instance of the module whose executable 
file contains the string resource. 
wlD WORD _ Specifies the integer identifier of the string to be loaded. 
[pBuffer LPSTR Points to the buffer that receives the string. 
nBufferMax int Specifies the maximum number of characters to be copied to 
the buffer. The string is truncated if it is longer than the number of 
characters specified. 
Return Value The return value specifies the actual number of characters copied into the buffer. It is zero 


if the string resource does not exist. 
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LOBYTE 
Syntax BYTE LOBYTE(x/nteger) 
This macro extracts the low-order byte from the short-integer value specified by the 
nInteger parameter. 
Parameter Type/Description 
ninteger int Specifies the value to be converted. 
Return Value The return value specifies the low-order byte of the value. 
LocalAlloc 
Syntax HANDLE §LocalAlloc(wF lags, wBytes) 


This function allocates the number of bytes of memory specified by the wBytes parameter 
from the local heap. The memory block can be either fixed or moveable, as specified by 
the wF lags parameter. 


Parameter Type/Description 


wFlags WORD _ Specifies how to allocate memory. It can be one or more of 
the following values: 


Value Meaning 


LMEM_DISCARDABLE Allocates discardable memory. Can 
only be used with 
LMEM_MOVEABLE. 


LMEM_FIXED Allocates fixed memory. 


LMEM_MODIFY Modifies the LMEM_DISCARD- 
ABLE flag. Can only be used with 
LMEM_DISCARDABLE. 


LMEM_MOVEABLE Allocates moveable memory. Cannot 
be used with LMEM_FIXED. 
LMEM_NOCOMPACT Does not compact or discard 


memory to satisfy the allocation 
request. 
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Return Value 


Comments 


LocalCompact 
Syntax 


Return Value 


Parameter Type/Description 
Value Meaning 
LMEM_NODISCARD Does not discard memory to satisfy 
the allocation request. 
LMEM_ZEROINIT Initializes memory contents to zero. 


Choose LMEM_FIXED or LMEM_MOVEABLE, and then combine 
others as needed by using the bitwise OR operator. 


wBytes WORD Specifies the total number of bytes to be allocated. 


The return value identifies the newly allocated local memory block if the function is 
successful. Otherwise, it is NULL. 


If the data segment that contains the heap is moveable, calling this function will cause the 
data segment to move if Windows needs to increase the size of the heap and cannot in- 
crease the size of the heap in its current location. An application can prevent Windows 
from moving the data segment by calling the LockData function to lock the data segment. 


If this function is successful, it allocates at least the amount requested. The actual amount 
allocated may be greater. To determine the actual amount allocated, call the LocalSize 
function. 


WORD _LocalCompact(wMinFree) 


This function generates the number of free bytes of memory specified by the wMinFree 
parameter by compacting, if necessary, the module’s local heap. The function checks the 
local heap for the specified number of contiguous free bytes. If the bytes do not exist, the 
LocalCompact function compacts local memory by first moving all unlocked moveable 
blocks into high memory. If this does not generate the requested amount of space, the 
function discards moveable and discardable blocks that are not locked down, until the 
requested amount of space is generated, whenever possible. 


Parameter Type/Description 


wMinFree WORD _ Specifies the number of free bytes desired. If wMinFree is 
zero, the function returns a value but does not compact memory. 


The return value specifies the number of bytes in the largest block of free local memory. 
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LocalDiscard 
Syntax HANDLE _ LocalDiscard(hMem) 


This function discards the local memory block specified by the Mem parameter. The lock 
count of the memory block must be zero. 


The local memory block is removed from memory, but its handle remains valid. An appli- 
cation can subsequently pass the handle to the LocalReAlloc function to allocate another 
local memory block identified by the same handle. 


Parameter Type/Description 
hMem HANDLE Identifies the local memory block to be discarded. 
Return Value The return value specifies the outcome of the function. It is NULL if the function is 


successful. Otherwise, it is equal to hMem. 


LocalFlags 
Syntax WORD LocalFlags(hMem) 


This function returns information about the specified local memory block. | 


Parameter Type/Description 


hMem HANDLE Identifies the local memory block. 


Return Value The return value contains one of the following memory-allocation flags in the high byte: 


Value Meaning 
LMEM_DISCARDABLE Block is marked as discardable. 
LMEM_DISCARDED Block has been discarded. 


The low byte of the return value contains the reference count of the block. Use the 
LMEM_LOCKCOUNT mask to retrieve the lock-count value from the return value. 
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LocalFree 
Syntax HANDLE LocalFree(hMem) 
This function frees the local memory block identified by the hMem parameter and 
invalidates the handle of the memory block. 
Parameter Type/Description 
hMem HANDLE Identifies the local memory block to be freed. 
Return Value The return value specifies the outcome of the function. It is NULL if the function is 
successful. Otherwise, it is equal to hMem. 
LocalHandle 
Syntax HANDLE = LocalHandle(wMem) 
This function retrieves the handle of the local memory object whose address is specified 
by the wMem parameter. 
Parameter Type/Description 
wMem WORD Specifies the address of a local memory object. 
Return Value The return value identifies the local memory object. 
Localinit 
Syntax BOOL LocalInit(wSegment, pStart, pEnd) 


This function initializes a local heap in the segment specified by the wSegment parameter. 


Parameter Type/Description 


wSegment WORD Specifies the segment address of the segment that is to 
contain the local heap. 


pStart PSTR Specifies the address of the start of the local heap within the 
segment. 
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LocalLock 


Return Value 


Comments 


LocalLock 
Syntax 


Return Value 


Parameter Type/Description 


pEnd PSTR = Specifies the address of the end of the local heap within the 
segment. 


The return value specifies a Boolean value that is nonzero if the heap is initialized. Other- 
wise, it is zero. 


If the pStart parameter is zero, the pEnd parameter specifies the offset of the last byte of 
the global heap from the end of the segment. For example, to initialize a 4096-byte heap 
with the first byte at byte 0, set pStart to 0 and pEnd to 4095. 


LocalInit calls the GlobalLock function for the data segment that contains the local heap. 
This ensures that the data segment will not be moved in memory. However, the memory 
will be moved if both of these conditions are true: 


1. The data segment is moveable. 


2. The application calls the LocalAlloc or LocalReAlloc function and, as a result, 
Windows must increase the size of the heap. If Windows cannot increase the size of the 
data segment that contains the local heap without moving it, Windows will move the 
data segment. 


An application can explicitly prevent Windows from moving the data segment by calling 
the LockData function to lock the data segment. 


An application can remove this initial lock count by calling the UnlockData function. 


PSTR = LocalLock(hMem) 


This function locks the local memory block specified by the Mem parameter. The block is 
locked into memory at the given address and its reference count is increased by one. 
Locked memory cannot be moved or discarded. The block remains locked in memory until 
its reference count is decreased to zero by using the LocalUnlock function. 


Parameter Type/Description 


hMem HANDLE Identifies the local memory block to be locked. 


The return value points to the first byte of memory in the local block if the function is 
successful. Otherwise, it is NULL. 


LocalReAlloc 
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LocalReAlloc 
Syntax 


HANDLE LocalReAlloc(hMem, wBytes, wFlags) 


This function changes the size of the local memory block specified by the Mem para- 
meter by increasing or decreasing its size to the number of bytes specified by! the wBytes 
parameter, or changes the attributes of the specified memory block. 


Parameter 


hMem 
wBytes 


wFlags 


Type/Description 


HANDLE Identifies the local memory block to be reallocated. 


WORD Specifies the new size of the memory block. 


WORD _ Specifies how to reallocate the local memory block. It can 
be one or more of the following values: 


Value 


LMEM_DISCARDABLE 


LMEM_MODIFY 


LMEM_MOVEABLE 


LMEM_NOCOMPACT 


Meaning 


Memory is discardable. This flag can 
only be used with LMEM_MODIFY. 


Memory flags are modified. The 
wBytes parameter is ignored. This 
flag can only be used with 
LMEM_DISCARDABLE. 


Memory is moveable. If wBytes is 
zero, this flag causes a previously 
fixed block to be freed or a pre- 
viously moveable object to be 
discarded (if the block’s reference 
count is zero). If wBytes is nonzero 
and the block specified by hMem is 
fixed, this flag allows the reallocated 
block to be moved to a new fixed lo- 
cation. (Note that the handle 
returned by the LocalReAlloc func- 
tion in this case may be different 
from the handle passed to the func- 
tion.) This flag cannot be used with 
LMEM_MODIFY. 


Memory will not be compacted or 
discarded to satisfy the allocation re- 
quest. This flag cannot be used with 
LMEM_MODIFY. 
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LocalShrink 


Return Value 


Comments 


LocalShrink 
Syntax 


Return Value 


Parameter Type/Description 
Value Meaning 
LMEM_NODISCARD Objects will not be discarded to 


satisfy the allocation request. This 
flag cannot be used with 
LMEM_MODIFY. 


LMEM_ZEROINIT If the block is growing, the addi- 
tional memory contents are 
initialized to zero. This flag cannot 
be used with LMEM_MODIFY. 


The return value identifies the reallocated local memory if the function is successful. It is 
NULL if the local memory block cannot be reallocated. 


The return value is always identical to the hMem parameter, unless the 
LMEM_MOVEABLE flag is used to allow movement of a fixed block of memory to a 
new fixed location. 


If the data segment that contains the heap is moveable, calling this function will cause the 
data segment to move if Windows must increase the size of the heap and cannot increase 
the size of the heap in its current location. An application can prevent Windows from 
moving the data segment by calling the LockData function to lock the data segment. 


WORD _sLocalShrink(/Seg, wSize) 


This function shrinks the specified heap to the size specified by the wSize parameter. 
The minimum size for the automatic local heap is defined in the application’s module- 
definition file. 


Parameter Type/Description 

hSeg HANDLE Identifies the segment that contains the local heap. 

wsSize WORD _ Specifies the size (in bytes) desired for the local heap after 
shrinkage. 


The return value specifies the size of the local heap after shrinkage. 


re 


LocalSize 
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Comments 


LocalSize 
Syntax 


Return Value 


Comments 


LocalUnlock 
Syntax 


Return Value 


If hSeg is zero, the LocalShrink function reduces the local heap in the current data seg- 
ment. Windows will not shrink that portion of the data segment that contains the stack and 
the static variables. 


Use the GlobalSize function to determine the new size of the data segment. 


WORD _LocalSize(hMem) 


This function retrieves the current size (in bytes) of the local memory block specified by 
the hMem parameter. 


Parameter Type/Description 


hMem HANDLE Identifies the local memory block. 


The return value specifies the size (in bytes) of the specified memory block. It is NULL if’ 
the given handle is not valid. 


The actual size of a memory block sometimes is larger than the size requested when the 
memory was allocated. 


BOOL = LocalUnlock(hMem) 


This function unlocks the local memory block specified by the hMem parameter and 
decreases the block’s reference count by one. The block is completely unlocked, and 
subject to moving or discarding, if the reference count is decreased to zero. 


Parameter Type/Description 


hMem HANDLE Identifies the local memory block to be unlocked. 


The return value is zero if the block’s reference count was decreased to zero. Otherwise, 
the return value is nonzero. 
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LockData 


LockData 
Syntax 


Return Value 


LockResource 
Syntax 


Return Value 


HANDLE  LockData(Dummy) 


This macro locks the current data segment in memory. It is intended to be used in modules 
that have moveable data segments. 


Parameter Type/Description 


Dummy int Is not used. It should be set to zero. 


The return value identifies the locked data segment if the function is successful. Other- 
wise, it is NULL. 


LPSTR = LockResource(/ResData) 


This function retrieves the absolute memory address of the loaded resource identified by 
the hResData parameter. The resource is locked in memory and the given address and its 
reference count are increased by one. The locked resource is not subject to moving or dis- 
carding. 


The resource remains locked in memory until its reference count is decreased to zero 
through calls to the FreeResource function. 


If the resource identified by hResData has been discarded, the resource-handler function 
(if any) associated with the resource is called before the LockResource function returns. 
The resource-handler function can recalculate and reload the resource if desired. After the 
resource-handler function returns, LockResource makes another attempt to lock the 
resource and returns with the result. 


Parameter Type/Description 


hResData HANDLE Identifies the desired resource. This handle is assumed 
to have been created by using the LoadResource function. 


The return value points to the first byte of the loaded resource if the resource was locked. 
Otherwise, it is NULL. 
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Comments 


LockSegment 
Syntax 


Return Value 


_lopen 
Syntax 


Using the handle returned by the FindResource function for the hResData parameter 
causes an error. 


Use the UnlockResource macro to unlock a resource that was locked by using Lock- 
Resource. 


HANDLE  LockSegment(wSegment) 


This function locks the segment whose segment address is specified by the wSegment para- 
meter. If wSegment is —1, the LockSegment function locks the current data segment. 


Except for nondiscardable segments in protected (standard or 386 enhanced) mode, the 
segment is locked into memory at the given address and its lock count is increased by one. 
Locked memory is not subject to moving or discarding except when a portion of the seg- 
ment is being reallocated by the GlobalReAlloc function. The segment remains locked in 
memory until its lock count is decreased to zero. 


In protected mode, LockSegment increments the lock count of discardable and automatic 
data segments only. 


Each time an application calls LockSegment for a segment, it must eventually call Un- 
lockSegment for the segment. The UnlockSegment function decreases the lock count for 
the segment. Other functions also can affect the lock count of a memory object. See the 
description of the GlobalFlags function for a list of the functions that affect the lock count. 


Parameter Type/Description 


wSegment WORD _ Specifies the segment address of the segment to be 
locked. If wSegment is —1, the LockSegment function locks the cur- 
rent data segment. 


The return value identifies the data segment if the function is successful. If the object has 
been discarded or an error occurs, the return value is NULL. 


int _lopen(/pPathName, iReadWrite) 


This function opens the file with the name specified by the /pPathName parameter. The 
iReadWrite parameter specifies the access mode of the file when the function opens it. If 
the file exists and is opened for writing only, the function truncates the file size to zero. 
When the function opens the file, the pointer is set to the beginning of the file. 
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_lopen 


Parameter 


lpPathName 


iReadWrite 


Type/Description 


LPSTR Points to a null-terminated character string that 
names the file to be opened. The string must consist of 
characters from the ANSI character set. 


int Specifies whether the function is to open the file with read 
access, write access, or both. The parameter must be one of the 


following values: 


OF_READ 
OF_READWRITE 


OF_SHARE_COMPAT 


OF_SHARE_DENY_NONE 


OF_SHARE_DENY_READ 


OF_SHARE_DENY_WRITE 


Meaning 


Opens the file for reading 
only. 


Opens the file for reading and 
writing. 


Opens the file with compati- 
bility mode, allowing any 
process on a given machine 
to open the file any number 
of times. OpenFile fails if 
the file has been opened with 
any of the other sharing 
modes. 


Opens the file without deny- 
ing other processes read or 
write access to the file. Open- 
File fails if the file has been 
opened in compatibility 

mode by any other process. 


Opens the file and denies 
other processes read access to 
the file. OpenFile fails if the 
file has been opened in com- 
patibility mode or for read 
access by any other process. 


Opens the file and denies 
other processes write access 
to the file. OpenFile fails if 
the file has been opened in 
compatibility or for write 
access by any other process. 
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Parameter Type/Description 


Value Meaning 


OF_SHARE_EXCLUSIVE Opens the file with exclusive 
mode, denying other 
processes both read and write 
access to the file. OpenFile 
fails if the file has been 
opened in any other mode for 
read or write access, even by 
the current process. 


OF_WRITE Opens the file for writing 
only. 


Return Value The return value specifies an MS-DOS file handle if the function opened the file. Other- 
wise, it is —1. 


LOWORD 
Syntax WORD LOWORD(dwinteger) 
This macro extracts the low-order word from the 32-bit integer value specified by the 
dwInteger parameter. 
Parameter Type/Description 
_dwinteger DWORD _ Specifies the value to be converted. 
Return Value The return value specifies the low-order word of the 32-bit integer value. 
LPtoDP 
Syntax BOOL LPtoDP(hDC, IpPoints, nCount) 


This function converts logical points into device points. The LPtoDP function maps the 
coordinates of each point specified by the JpPoints parameter from GDI’s logical coordi- 
nate system into a device coordinate system. The conversion depends on the current map- 
ping mode. . 
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_tread 


Return Value 


_lread 
Syntax 


Return Value 


Istrcat 
Syntax 


Parameter Type/Description 

hDC HANDLE Identifies the device context. 

IpPoints LPPOINT Points to an array of points. Each point in the array is a 
POINT data structure. 

nCount int Specifies the number of points in the array. 


The return value specifies whether or not all points are converted. It is nonzero if all points 
are converted. Otherwise, it is zero. 


int _lread(hFile, IpBuffer, wBytes) 


This function reads data from the file identified by the hFile parameter. The wBytes para- 
meter specifies the number of bytes to read. The function return value indicates the num- 
ber of bytes actually read. The return value is zero if the function attempted to read the file 
at EOF. 


Parameter Type/Description 

hFile int Specifies the MS-DOS file handle of the file to be read. 

[pBuffer LPSTR Points to a buffer that is to receive the data read from the 
file. 

wBytes WORD _ Specifies the number of bytes to be read from the file. 


The return value indicates the number of bytes which the function actually read from the 
file, or —1 if the function fails. The return value is less than wBytes if the function en- 
countered the end of the file (EOF) before reading the specified number of bytes. 


LPSTR _Istreat(/pString/, lpString2) 


This function concatenates /pString2 to the string specified by /pString], terminates the re- 
sulting string with a null character, and returns a far pointer to the concatenated string 
(IpString1). 


All strings must be less than 64K in size. 


Istremp 
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Return Value 


Istremp 
Syntax 


Return Value 


Parameter Type/Description 


[pString] LPSTR Points to byte array containing a null-terminated string to 
which the function is to append /pString2. The byte array containing 
the string must be large enough to contain both strings. 


[pString2 LPSTR Points to the null-terminated string which the function is 
to append to /pString1. 


The return value specifies a pointer to /pString1. It is zero if the function fails. 


int Istremp(/pSzring/, lpString2) 


This function compares the two strings identified by /pString/] and IpString2 lexicographi- 
cally and returns a value indicating their relationship. The comparison is made based on 
the current language selected by the user at setup or with the Control Panel. The compari- 
son is case-sensitive. This function is not equivalent to the stremp C run-time library func- 
tion. 


All strings must be less than 64K in size. 


Parameter Type/Description 

IpString1 LPSTR Points to the first null-terminated string to be compared. 

IpString2 LPSTR Points to the second null-terminated string to be com- 
pared. 


The return value indicates whether /pString/ is less than, equal to, or greater than 
IpString2. This relationship is outlined in the following: 


Value Meaning 
<0 - IpString] is less than IpString2. 
=0 IpString] is identical to [pString2. 


>0 IpString] is greater than IpString2. 
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Istrempi 


Istrempi [3.0 | 
Syntax 


Return Value 


Istrcpy 
Syntax 


int Istrempi(/pString1, IpString2) 


This function compares the two strings identified by /pString/] and IpString2 lexicographi- 
cally and returns a value indicating their relationship. The comparison is made based on 

the current language selected by the user at setup or with the Control Panel. The compari- 
son is case-sensitive. This function is not equivalent to the strempi C run-time library func- 
tion. 


All strings must be less than 64K in size. 


Parameter Type/Description 

IpString1 LPSTR Points to the first null-terminated string to be compared. 

IpString2 LPSTR Points to the second null-terminated string to be com- 
pared. 


The return value indicates whether /pString/ is less than, equal to, or greater than 
IpString2. This relationship is outlined in the following table: 


Value Meaning 

<0 IpString] is less than [pString2. 
=0 IpString] is identical to [pString2. 
>0 IpString] is greater than IpString2. 


LPSTR | Istrepy(/pString/, IpString2) 


This function copies /pString2, including the terminating null character, to the location 
specified by /pString1, and returns /pString1. 


All strings must be less than 64K in size. 


es peek eet 
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Parameter Type/Description 
IpString1 LPSTR Points to a buffer to receive the contents of /pString2. The 
buffer must be large enough to contain [pString2. 
IpString2 LPSTR Points to the null-terminated string to be copied. 
Return Value The return value specifies a pointer to /pString/. It is zero if the function fails. 
Istrlen 
Syntax int Istrlen(/pString) 
This function returns the length, in bytes, of /pString, not including the terminating null 
character. 
All strings must be less than 64K in size. 
Parameter Type/Description 
IpString LPSTR Points to a null-terminated string. 
Return Value The return value specifies the length of /pString. There is no error return. 
_lwrite 
Syntax ~ int _Iwrite(hFile, lpBuffer, wBytes) 


This function writes data into the file specified by the hFile parameter. The wBytes para- 
meter specifies the number of bytes to write from the buffer identified by /pBuffer. The 
function return value indicates the number of bytes actually written to the file. 


Parameter Type/Description 

hFile int Specifies the MS-DOS file handle of the file to be read. 

lpBuffer LPSTR Points to a buffer that contains the data to be written to the 
file. 


wBytes WORD _ Specifies the number of bytes to be written to the file. 
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Return Value The return value indicates the number of bytes actually written to the file, or —1 if the 
function fails. 


Comments The buffer specified by /pBuffer cannot extend past the end of a segment. 


oM—nm 


MAKEINTATOM 


MAKEINTATOM 
Syntax 


Return Value 
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LPSTR MAKEINTATOM(wInteger) 
This macro creates an integer atom that represents a character string of decimal digits. 


Integer atoms created by this macro can be added to the atom table by means of the Add- 
Atom function. 


Parameter Type/Description 


winteger WORD _Specifies the numeric value of the atom’s character string. 


The return value points to the atom created for the given integer. 


Comments The DeleteAtom function always succeeds for integer atoms, even though it does nothing, 
and the GetAtomName function always returns the string form of the integer atom. 

MAKEINTRESOURCE 

Syntax LPSTR MAKEINTRESOURCE (nJnteger) 


Return Value 


Syntax 


This macro converts an integer value into a long pointer to a string, with the high-order 
word of the long pointer set to zero. 


Parameter Type/Description 


nInteger int Specifies the integer value to be converted. 


The return value points to a string. 


MAKELONG 


DWORD MAKELONG(wLow, wHigh) 


This macro creates an unsigned long integer by concatenating two integer values, specified 
by the wLow and wHigh parameters. 
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Parameter Type/Description 
wLow WORD Specifies the low-order word of the new long value. 
wHigh WORD _ Specifies the high-order word of the new long value. 
Return Value The return value specifies an unsigned long-integer value. 
MAKEPOINT 
Syntax POINT MAKEPOINT(dwinteger) 
This macro converts a long value that contains the x- and y-coordinates of a point into a 
POINT data structure. 
Parameter Type/Description 
dwInteger DWORD _ Specifies the x- and y-coordinates of a point. 
Return Value The return value specifies the POINT data structure. 
MakeProcinstance 
Syntax FARPROC MakeProclInstance(/pProc, hinstance) 


This function creates a procedure-instance address. A procedure-instance address points to 
prolog code that is executed before the function is executed. The prolog binds the data seg- 
ment of the instance specified by the h/nstance parameter to the function pointed to by the 
IpProc parameter. When the function is executed, it has access to variables and data in that 
instance’s data segment. 


Parameter Type/Description 

IpProc FARPROC _Is a procedure-instance address. 

hInstance HANDLE Identifies the instance associated with the desired data 
segment. 


Return Value The return value points to the function if the function is successful. Otherwise, it is NULL. 


NE nm : 
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Comments 


The MakeProclInstance function must only be used to access functions from instances of 
the current module. The function is not required for library modules. 


After MakeProcInstance has been called for a particular function, all calls to that function 
should be made through the retrieved address. 


MakeProclInstance will create more than one procedure instance. An application should 
not call MakeProcInstance more than once using the same function and instance handle 
to avoid wasting memory. 


To bind a data segment to a function, the function must be exported in the EXPORTS 
statement of the module-definition file. 


MapDialogRect 


Syntax 


Return Value 


Comments 


void MapDialogRect(hD/g, [pRect) 


This function converts the dialog-box units given in the /pRect parameter to screen units. 
Dialog-box units are stated in terms of the current dialog base unit derived from the aver- 
age width and height of characters in the system font. One horizontal unit is one-fourth of 
the dialog base width unit, and one vertical unit is one-eighth of the dialog base height 
unit. The GetDialogBaseUnits function returns the dialog base units in pixels. 


The MapDialogRect function replaces the dialog-box units in /pRect with screen units 


(pixels), so that the rectangle can be used to create a dialog box or position a control within 
a box. 


Parameter Type/Description 


hDlg HWND Identifies a dialog box. 
IpRect LPRECT Points toa RECT data structure that contains the dialog- 


box coordinates to be converted. 


None. 


The hDlg parameter must be created by using the CreateDialog or DialogBox function. 
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MapVirtualKey 


MapVirtualKey 


Syntax 


Return Value 


max 
Syntax 


WORD MapVirtualKey(wCode, wMapType) 


This function accepts a virtual-key code or scan code for a key and returns the correspond- 
ing scan code, virtual-key code, or ASCII value. The value of the wMapType parameter de- 
termines the type of mapping which this function performs. 


Parameter Description 

wCode WORD _ Specifies the virtual-key code or scan code for a key. The 
interpretation of the wCode parameter depends on the value of the 
wMapType parameter. 

wMapType WORD _ Specifies the type of mapping to be performed. The | 
wMapType parameter can be any of the following values: 

Value Meaning 

0 The wCode parameter specifies a virtual-key code, 
and the function returns the corresponding scan 
code. 

1 The wCode parameter specifies a scan code, and 
the function returns the corresponding virtual-key 
code. 

2 The wCode parameter specifies a virtual-key code, 
and the function returns the corresponding un- 
shifted ASCII value. 


Other values are reserved. 


The return value depends on the value of the wCode and wMapType parameters. See the 
description of the wMapType parameter for more information. 


int} max(valuel, value2) 


This macro returns the greater of the values contained in the value/ and value2 parameters. 
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Return Value 


Comments 


MessageBeep 
Syntax 


Return Value 


MessageBox 
Syntax 


Parameter Description 
valuel Specifies the first of two values. 
value2 Specifies the second of two values. 


The return value specifies value] or value2, whichever is greater. 


The values identified by the value] and value2 parameters can be any ordered type. 


void MessageBeep(w7ype) 


This function generates a beep at the system speaker. 


Parameter Type/Description 
wType WORD Is not used. It should be set to zero. 
None. 


int MessageBox(hWndParent, IpText, lpCaption, wType) 


This function creates and displays a window that contains an application-supplied message 
and caption, plus any combination of the predefined icons and push buttons described in 
the following list. 


Parameter Type/Description 


hWndParent HWND Identifies the window that owns the message box. 


[pText LPSTR Points to a null-terminated string containing the message 
to be displayed. 
IpCaption LPSTR Points to a null-terminated character string to be used for 


the dialog-box caption. If the /pCaption parameter is NULL, the de- 
fault caption “Error” is used. 
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MessageBox 


Return Value 


Comments 


Parameter Type/Description 


wType WORD Specifies the contents of the dialog box. It can be any com- 
bination of the values shown in Table 4.11, “Message Box Types,” 
joined by the bitwise OR operator. 


The return value specifies the outcome of the function. It is zero if there is not enough 
memory to create the message box. Otherwise, it is one of the following menu-item values 
returned by the dialog box: 


Value Meaning 

IDABORT Abort button pressed. 
IDCANCEL Cancel button pressed. 
IDIGNORE Ignore button pressed. 
IDNO No button pressed. 
IDOK OK button pressed. 
IDRETRY Retry button pressed. 
IDYES Yes button pressed. 


If a message box has a Cancel button, the IDCANCEL value will be returned if either the 
ESCAPE key or Cancel button is pressed. If the message box has no Cancel button, pressing 
the ESCAPE key has no effect. . 


When a system-modal message box is created to indicate that the system is low on 
memory, the strings passed as the /pText and [pCaption parameters should not be taken 
from a resource file, since an attempt to load the resource may fail. 


When an application calls the MessageBox function and specifies the MB_ICONHAND 
and MB_SYSTEMMODAL flags for the w7ype parameter, Windows will display the re- 
sulting message box regardless of available memory. When these flags are specified, 
Windows limits the length of the message-box text to one line. 


If a message box is created while a dialog box is present, use the handle of the dialog box 
as the hWndParent parameter. The hWndParent parameter should not identify a child 
window, such as a dialog-box control. 


MessageBox 
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Table 4.11 shows the message box types. 


Table 4.11 Message Box Types 


Value 


MB_ABORTRETRYIGNORE 


MB_APPLMODAL 


MB_DEFBUTTON1 


MB_DEFBUTTON2 
MB_DEFBUTTON3 
MB_ICONASTERISK 
MB_ICONEXCLAMATION 
MB_ICONHAND 
MB_ICONINFORMATION 


MB_ICONQUESTION 
MB_ICONSTOP 
MB_OK 
MB_OKCANCEL 


MB_RETRYCANCEL 


MB_SYSTEMMODAL 


Meaning 


Message box contains three push buttons: Abort, Retry, 
and Ignore. 


The user must respond to the message box before con- 
tinuing work in the window identified by the 
hWndParent parameter. However, the user can move to 
the windows of other applications and work in those 
windows. MB_APPLMODAL is the default if neither 
MB_SYSTEMMODAL nor MB_TASKMODAL are 
specified. 


First button is the default. Note that the first button is al- 
ways the default unless MB_DEFBUTTON2 or 
MB_DEFBUTTONS3 is specified. 


Second button is the default. 

Third button is the default. 

Same as MB_ICONINFORMATION. 

An exclamation-point icon appears in the message box. 
Same as MB_ICONSTOP. 


An icon consisting of a lowercase i in a circle appears in 
the message box. 


A question-mark icon appears in the message box. 
A stop sign icon appears in the message box. 
Message box contains one push button: OK. 


Message box contains two push buttons: OK and Can- 
cel. 


Message box contains two push buttons: Retry and Can- 
cel. 


All applications are suspended until the user responds to 
the message box. Unless the application specifies 
MB_ICONHAND, the message box does not become 
modal until after it is created; consequently, the parent 
window and other windows continue to receive mes- 
sages resulting from its activation. System-modal 
message boxes are used to notify the user of serious, 
potentially damaging errors that require immediate atten- 
tion (for example, running out of memory). 


4-309 min 


Table 4.11 Message Box Types (continued) 


Value Meaning 


MB_TASKMODAL Same as MB_APPMODAL except that all the top-level 
windows belonging to the current task are disabled if the 
hWndOwner parameter is NULL. This flag should be 
used when the calling application or library does not 
have a window handle available, but still needs to pre- 
vent input to other windows in the current application 
without suspending other applications. 


MB_YESNO Message box contains two push buttons: Yes and No. 


MB_YESNOCANCEL Message box contains three push buttons: Yes, No, and 
Cancel. 


min 
Syntax int min(valuel, value2) 


This macro returns the lesser of the values specified by the value/ and value2 parameters, 
respectively. 


Parameter Description 
valuel Specifies the first of two values. 


value2 Specifies the second of two values. 


Return Value The return value specifies value] or value2, whichever is less. 


Comments The values identified by the value/ and value2 parameters can be any ordered type. 


ModifyMenu 


Syntax BOOL ModifyMenu(hMenu, nPosition, wFlags, wIDNewItem, lpNewlItem) 


This function changes an existing menu item at the position specified by the nPosition 
parameter. The application specifies the new state of the menu item by setting values in the 
wF lags parameter. If this function replaces a pop-up menu associated with the menu item, 
it destroys the old pop-up menu and frees the memory used by the pop-up menu. 


ModifyMenu 
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Parameter 
hMenu 


nPosition 


wF lags 


wlDNewltem 


lpNewlItem 


Type/Description 
HMENU Identifies the menu to be changed. 


WORD _ Specifies the menu item to be changed. The interpretation 
of the nPosition parameter depends upon the setting of the wFlags 
parameter. 


If wFlags is: nPosition 


MF_BYPOSITION Specifies the position of the existing 
menu item. The first item in the menu is 
at position zero. 


MF_BYCOMMAND Specifies the command ID of the existing 
menu item. 


WORD _ Specifies how the nPosition parameter is interpreted and 
information about the changes to be made to the menu item. It con- 
sists of one or more values listed in the following “Comments” 
section. 


WORD _Specifies either the command ID of the modified menu 
item or, if wFlags is set to MF_POPUP, the menu handle of the pop- 
up menu. 


LPSTR Specifies the content of the changed menu item. If 

wF lags is set to MF_STRING (the default), then JpNewItem is a 
long pointer to a null-terminated character string. If wFlags is set to 
MF_BITMATP instead, then /pNew/tem contains a bitmap handle 


(HBITMAP) in its low-order word. If wFlags is set to MF_OWNER- 


DRAW, IpNewlItem specifies an application-supplied 32-bit value 
which the application can use to maintain additional data associated 
with the menu item. This 32-bit value is available to the application 
in the itemData field of the structure, pointed to by the /Param para- 
meter of the following messages: 


WM_MEASUREITEM 
WM_DRAWITEM 


These messages are sent when the menu item is initially displayed, or 
is changed. 


Return Value The return value specifies the outcome of the function. It is TRUE if the function is 
successful. Otherwise, it is FALSE. 
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ModifyMenu 


Comments 


Whenever a menu changes (whether or not the menu resides in a window that is dis- 
played), the application should call DrawMenuBar. In order to change the attributes of ex- 
isting menu items, it is much faster to use the CheckMenultem and EnableMenulItem 


functions. 


Each of the following groups lists flags that should not be used together: 


= MF_BYCOMMAND and MF_BYPOSITION 

= MF_DISABLED, MF_ENABLED, and MF_GRAYED 

= MF_BITMAP, MF_STRING, MF_OWNERDRAW, and MF_SEPARATOR 
= MF_MENUBARBREAK and MF_MENUBREAK 

= MF_CHECKED and MF_UNCHECKED 


The following list describes the flags which may be set in the wF/ags parameter: 


Value 


MF_BITMAP 


MF_BYCOMMAND 


MF_BYPOSITION 


MF_CHECKED 


MF_DISABLED 


MF_ENABLED 


MF_GRAYED 


MF_MENUBARBREAK 


Meaning 


Uses a bitmap as the menu item. The low-order word of 
the [pNewltem parameter contains the handle of the bit- 
map. 


Specifies that the nPosition parameter gives the menu 
item control ID number. This is the default if neither 
MF_BYCOMMAND nor MF_POSITION is set. 


Specifies that the nPosition parameter gives the position 
of the menu item to be changed rather than an ID num- 
ber. 


Places a checkmark next to the menu item. If the applica- 
tion has supplied checkmark bitmaps (see SetMenu- 
ItemBitmaps), setting this flag displays the “checkmark 
on” bitmap next to the menu item. 


Disables the menu item so that it cannot be selected, but 
does not gray it. 


Enables the menu item so that it can be selected and re- 
stores it from its grayed state. 


Disables the menu item so that it cannot be selected and 
grays it. 


Same as MF_MENUBREAK except that for pop-up 
menus, separates the new column from the old column 
with a vertical line. 


MoveTo 
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Value 


MF_MENUBREAK 


MF_OWNERDRAW 


MF_POPUP 


MF_SEPARATOR 


MF_STRING 


MF_UNCHECKED 


MoveTo 


Meaning 


Places the menu item on a new line for static menu-bar 
items. For pop-up menus, this flag places the item in a 
new column, with no dividing line between the columns. 


Specifies that the menu item is an owner-draw item. The 
window that owns the menu receives a WM_MEASURE- 
ITEM message when the menu is displayed for the first 
time to retrieve the height and width of the menu item. 
The WM_DRAWITEM message is then sent whenever 
the owner must update the visual appearance of the 

menu item. This option is not valid for a top-level menu 
item. 


Specifies that the item has a pop-up menu associated 
with it. The w/DNewlItem parameter specifies a handle to 
a pop-up menu to be associated with the menu item. Use 
this flag for adding either a top-level pop-up menu or 
adding a hierarchical pop-up menu to a pop-up menu 
item. 


Draws a horizontal dividing line. You can only use this 
flag in a pop-up menu. This line cannot be grayed, dis- 
abled, or highlighted. The IpNewItem and wIDNewItem 
parameters are ignored. 


Specifies that the menu item is a character string; the 
lpNewltem parameter points to the string for the menu 
item. 


Does not place a checkmark next to the menu item. No 
checkmark is the default if neither MF_CHECKED nor 
MF_UNCHECKED is set. If the application has supplied 
checkmark bitmaps (see SetMenultemBitmaps), setting 
this flag displays the “checkmark off’ bitmap next to the 
menu item. 


Syntax DWORD MoveTo(hDC, xX, Y) 


This function moves the current position to the point specified by the X and Y parameters. 
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Parameter Type/Description 
hDC HDC Identifies the device context. 
X int Specifies the logical x-coordinate of the new position. 
Y int Specifies the logical y-coordinate of the new position. 
Return Value The return value specifies the x- and y-coordinates of the previous position. The y-coordi- 


nate is in the high-order word; the x-coordinate is in the low-order word. 


Comments Although the MoveTo function has no output, it affects other output functions that use the 
current position. 

MoveWindow 

Syntax void MoveWindow(hWnd, xX, Y, nWidth, nHeight, bRepaint) 


This function causes a WM_SIZE message to be sent to the given window. The X, Y, 
nWidth, and nHeight parameters give the new size of the window. 


Parameter Type/Description 

hWnd HWND Identifies a pop-up or child window. 

X int Specifies the new x-coordinate of the upper-left corner of the 
window. 

Y int Specifies the new y-coordinate of the upper-left corner of the 


window. For pop-up windows, X and Y are in screen coordinates 
(relative to the upper-left corner of the screen). For child windows, 
they are in client coordinates (relative to the upper-left corner of the 
parent window’s client area). 


nWidth int Specifies the new width of the window. 
nHeight int Specifies the new height of the window. 
bRepaint BOOL Specifies whether or not the window is repainted after 


moving. If bRepaint is zero, the window is not repainted. 


Return Value None. 
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Comments Any child or pop-up window has a minimum width and height. These minimums depend 
on the style and content of the window. Any attempt to make the width and height smaller 
than the minimum by using the MoveWindow function will fail. The WM_SIZE message 
created by this function gives the new width and height of the client area of the window, 
not of the full window. 


MulDiv 


Syntax int MulDiv(nNumber, nNumerator, nDenominator) 


This function multiplies two word-length values and then divides the result by a third 
word-length value. The return value is the final result, rounded to the nearest integer. 


Parameter Type/Description 
nNumber int Specifies the number to be multiplied by nNumerator. 
nNumerator int Specifies the number to be multiplied by nNumber. 

~ nDenominator int Specifies the number by which the result of the multiplica- 


tion is to be divided. 


Return Value The return value is the result of the multipliation and division. The return value is 32,767 
. or —32,767 if either an overflow occurred or wDenominator was zero. 
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NetBIOSCall 


This function allows an applications to issue the NETBIOS interrupt SCH. An application 
should call this function instead of directly issuing a NETBIOS SCH interrupt to preserve 
compatibility with future Microsoft products. 


An application can call this function only from an assembly-language routine. It is 
exported from KERNEL.EXE and is not defined in any Windows include files. 


To use this function call, an application should declare it in an assembly-language program 
as shown: 


extrn NETBIOSCALL :far 


If the application includes CMACROS.INC, the application declares it as shown: 


externFP NetBI0SCal] 


Before calling NetBIOSCall, all registers must be set as for an actual INT 5CH. All 
registers at the function’s exit are the same as for the corresponding INT 5CH function. 


This function has no parameters and no return value. 
The following is an example of how to use the NetBIOSCall function: 


extrn NETBIOSCALL : far 


;set registers 
cCall NetBIOSCal] 
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OemKeyScan 


Syntax 


Return Value 


Comments 
aa 
a 
= 
OemToAnsi 
Syntax 


DWORD OemKeyScan(wOemChar) 


This function maps OEM ASCII codes 0 through OxOFF into the OEM scan codes and 
shift states. It provides information which allows a program to send OEM text to another 
program by simulating keyboard input and is used specifically for this purpose by 
Windows in 386 enhanced mode. 


Parameter Type/Description 


wOemChar WORD Specifies the ASCII value of the OEM character. 


The return value contains in its low-order word the scan code of the OEM character iden- 
tified by the wOemChar parameter. The high-order word of the return value contains flags 
which indicate the shift state. The following lists the flag bits and their meanings: 


Bit Meaning 
2 CTRL key is pressed. 
1 Either SHIFT key is pressed. 


If the character is not defined in the OEM character tables, both the low-order and high- 
order words of the return value contain —1. 


This function does not provide translations for characters which require CTRL-ALT or dead 
keys. Characters not translated by this function must be copied by simulating input using 
the “ALT + keypad” mechanism. The NUMLOCK key must be off. 


This function calls the VkKeyScan function in recent versions of the keyboard drivers. 


int OemToAnsi(/pOemsStr, lpAnsiStr) 


This function translates the string pointed to by the JpOemStr parameter from the OEM- 
defined character set into the ANSI character set. The string can be greater than 64K in 
length. 
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Parameter Type/Description 


lpOemStr LPSTR Points to a null-terminated string of characters from the 
OEM-defined character set. 


IpAnsiStr LPSTR Points to the location where the translated string is to be 
copied. The /pAnsiStr parameter can be the same as /pOemStr to 
translate the string in place. 


Return Value The return value is always —1. 


OemToAnsiBuff 
Syntax void OemToAnsiBuff(/pOemStr, lpAnsiStr, nLength) 


This function translates the string in the buffer pointed to by the /pOemStr parameter from 
the OEM-defined character set into the ANSI character set. 


Parameter — Type/Description 


IpOemStr LPSTR Points to a buffer containing one or more characters from 
the OEM-defined character set. 


lpAnsiStr LPSTR Points to the location where the translated string is to be 
copied. The /pAnsiStr parameter can be the same as /JpOemsStr to 
translate the string in place. 


nLength WORD _ Specifies the number of characters in the buffer identified 
by the JpOemStr parameter. If nLength is zero, the length is 64K 
(65,536). 
Return Value None. 
OffsetClipRgn 
Syntax int OffsetClipRgen(ZDC, X, Y) 


This function moves the clipping region of the given device by the specified offsets. The 
function moves the region X units along the x-axis and Y units along the y-axis. 


OffsetRect 4-318 


Parameter Type/Description 
hDC HDC Identifies the device context. 
x int Specifies the number of logical units to move left or right. 


Y int Specifies the number of logical units to move up or down. 


Return Value The return value specifies the new region’s type. It can be any one of the following values: 


Value Meaning 

COMPLEXREGION Clipping region has ovedapping borders. 
ERROR Device context is not valid. 
NULLREGION Clipping region is empty. 
SIMPLEREGION Clipping region has no overlapping borders. 


OffsetRect 
Syntax . void OffsetRect(/pRect, X, Y) 


This function moves the given rectangle by the specified offsets. The OffsetRect function 
moves the rectangle X units along the x-axis and Y units along the y-axis. The X and Y para- 
meters are signed values, so the rectangle can be moved left or right, and up or down. 


Parameter Type/Description 


IpRect LPRECT Points to a RECT data structure that contains the 
rectangle to be moved. 


Xx int Specifies the amount to move left or right. It must be negative 
to move left. 


 § int Specifies the amount to move up or down. It must be negative 
to move up. 


_ Return Value None. 


Comments The coordinate values of a rectangle must not be greater than 32,767 or less than —32,768. 
The X and Y parameters must be chosen carefully to prevent invalid rectangles. 
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OffsetRgn 
Syntax int OffsetRgn(hRgn, X, Y) 


This function moves the given region by the specified offsets. The function moves the re- 
gion X units along the x-axis and Y units along the y-axis. 


Parameter Type/Description 
hRgn HRGN Identifies the region to be moved. 
Xx int Specifies the number of units to move left or right. 


Y int Specifies the number of units to move up or down. 


Return Value The return value specifies the new region’s type. It can be any one of the following values: 


Value Meaning 

COMPLEXREGION Region has overlapping borders. 
ERROR Region handle is not valid. 
NULLREGION Region is empty. 
SIMPLEREGION Region has no overlapping borders. 


_ Comments The coordinate values of a region must not be greater than 32,767 or less than —32,768. 
The X and Y parameters must be carefully chosen to prevent invalid regions. 


OffsetViewportOrg 
Syntax DWORD OffsetViewportOrg(hDC, x, Y) 


This function modifies the viewport origin relative to the current values. The formulas are 
written as follows: 


xNewVO = xOldVO + X 
yNewVO = yOldVO + Y 


The new origin is the sum of the current origin and the X and Y values. 
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Parameter Type/Description 
hDC HDC Identifies the device context. 
Xx int Specifies the number of device units to add to the current 


origin’s x-coordinate. 


Y int Specifies the number of device units to add to the current 
origin’s y-coordinate. 


Return Value The return value specifies the previous viewport origin (in device coordinates). The pre- 
vious y-coordinate is in the high-order word; the previous x-coordinate is in the low-order 
word. 

OffsetWindowOrg 

Syntax DWORD OffsetWindowOrg(hDC, X, Y) 


This function modifies the viewport origin relative to the current values. The formulas are 
written as follows: 


xNewW0O = xOldWO + X 
yNewWO = yOldWO + Y 


The new origin is the sum of the current origin and the X and Y values. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
Xx int Specifies the number of logical units to add to the current 


origin’s x-coordinate. 


Y int Specifies the number of logical units to add to the current 
origin’s y-coordinate. 


Return Value The return value specifies the previous window origin (in logical coordinates). The pre- 
vious y-coordinate is in the high-order word; the previous x-coordinate is in the low-order 
word. 
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OpenClipboard 


OpenClipboard 


Syntax 


Return Value 


Comments 


OpenComm 
Syntax 


Return Value 


BOOL OpenClipboard(iWnd) 


This function opens the clipboard for examination and prevents other applications from 
modifying the clipboard contents. 


Parameter . Type/Description 
hWnd HWND Identifies the window to be associated with the open clip- 
board. 


The return value specifies the status of the clipboard. It is nonzero if the clipboard is 
opened. If the clipboard has already been opened by another application, the return value 
is Zero. 


An application should call the CloseClipboard function for every successful call to the 
OpenClipboard function. 


int OpenComm(/pComName, winQueue, wOutQueue) 


This function opens a communication device and assigns an nCid handle to it. The com- 
munication device is initialized to a default configuration. The SetCommState function 
should be used to initialize the device to alternate values. The OpenComm function allo- 
cates space for receive and transmit queues. The queues are used by the interrupt-driven 
transmit/receive software. 


Parameter Type/Description 


lpComName LPSTR Points to a string which contains COMn or LPTn, where n 
ranges from 1 to the number of communication devices available for 
the particular type of I/O port. 


winQueue WORD Specifies the size of the receive queue. 


wOutQueue WORD Specifies the size of the transmit queue. 


The return value specifies the open communication device. If an error occurs, the return 
value is one of the following negative error values: 


OpenFil 
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Comments 


OpenFile 
Syntax 


Value 
IE_BADID 
IE_BAUDRATE 
IE_BYTESIZE 
IE_DEFAULT 
IE_HARDWARE 
IE_MEMORY 
IE_NOPEN 
IE_OPEN 


Meaning 

Invalid or unsupported ID. 
Unsupported baud rate. 
Invalid byte size. 

Error in default parameters. 
Hardware not present. 
Unable to allocate queues. 
Device not open. 


Device already open. 


LPT ports are not interrupt driven. For these ports, the n/nQueue and nOutQueue 
parameters are ignored, and the queue size is set to zero. 


int OpenFile(/pFileName, IpReOpenBuff, wStyle) 


This function creates, opens, reopens, or deletes a file. 


Parameter 


lpFileName 


[pReOpenBuff 


wStyle 


Type/Description 


LPSTR Points to a null-terminated character string that 
names the file to be opened. The string must consist of 
characters from the ANSI character set. 


LPOFSTRUCT Points to the OFSTRUCT data structure 
that is to receive information about the file when the file is first 
opened. The structure can be used in subsequent calls to the 
OpenFile function to refer to the open file. 


The szPathName field of this data structure contains characters 
from the OEM character set. 


WORD _ Specifies the action to take. These styles can be com- 
bined by using the bitwise OR operator: 
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Parameter 


vo 


Type/Description 


Value 


OF_CANCEL 


OF_CREATE 


OF_DELETE 
OF_EXIST 


OF_PARSE 


OF_PROMPT 


OF_READ 
OF_READWRITE 


OF_REOPEN 


OpenFile 


Meaning 


Adds a Cancel button to the 


‘OF_PROMPT dialog box. 


Pressing the Cancel button 
directs OpenFile to return a 
file-not-found error message. 


Directs OpenFile to create a 
new file. If the file already ex- 
ists, it is truncated to zero 
length. 


Deletes the file. 


Opens the file, and then 
closes it. Used to test for file 
existence. 


Fills the OFSTRUCT data 
structure but carries out no 
other action. 


Displays a dialog box if the 
requested file does not exist. 
The dialog box informs the 
user that Windows cannot 
find the file and prompts the 
user to insert the file in drive 
A. 


Opens the file for reading 
only. 


Opens the file for reading 
and writing. 


Opens the file using informa- 
tion in the re-open buffer. 


OpenFile | 


Parameter 


Type/Description 


Value 


OF_SHARE_COMPAT 


OF_SHARE_DENY_NONE 


OF_SHARE_DENY_READ 


OF_SHARE_DENY_WRITE 


OF_SHARE_EXCLUSIVE 
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Meaning 


Opens the file with compati- 
bility mode, allowing any 
process on a given machine 
to open the file any number 
of times. OpenFile fails if 
the file has been opened with 
any of the other sharing 
modes. 


Opens the file without deny- 
ing other processes read or 
write access to the file. Open- 
File fails if the file has been 
opened in compatibility 

mode by any other process. 


Opens the file and denies 
other processes read access to 
the file. OpenFile fails if the 
file has been opened in com- 
patibility mode or for read 
access by any other process. 


Opens the file and denies 
other processes write access 
to the file. OpenFile fails if 
the file has been opened in 
compatibility or for write 
access by any other process. 


Opens the file with exclusive 
mode, denying other 
processes both read and write 
access to the file. OpenFile 
fails if the file has been 
opened in any other mode for 
read or write access, even by 
the current process. 
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Openicon 


Return Value 


Comments 


Openicon 
Syntax 


Parameter Type/Description 

Value Meaning 

OF_VERIFY Verifies that the date and 
time of the file are the same 
as when it was previously 
opened. Useful as an extra 
check for read-only files. 

OF_WRITE Opens the file for writing 


only. 


The return value specifies a DOS file handle if the function is successful. Otherwise, it is 
-l. 


If the /pFileName parameter specifies a filename and extension only, this function searches 
for a matching file in the following directories: 
1. The current directory. 


2. The Windows directory (the directory containing WIN.COM); the Get- 
WindowsDirectory function obtains the pathname of this directory. 


3. The Windows system directory (the directory containing such system files as KER- 
NEL.EXE); the GetSystemDirectory function obtains the pathname of this directory. 


4. Any of the directories listed in the PATH environment variable. 


5. Any directory in the list of directories mapped in a network. 


Windows searches the directories in the listed order. 
The /pFileName parameter cannot contain wildcard characters. 


To close the file after use, the application should call the _Iclose function. 


BOOL OpenlIcon(hWnd) 


This function activates and displays an iconic (minimized) window. Windows restores it to 
its original size and position. 


OpenSound 
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Return Value 


OpenSound 
Syntax 


Return Value 


Parameter Type/Description 


hWnd HWND Identifies the window. 


The return value specifies the outcome of the function. It is nonzero if the function is 
successful. Otherwise, it is zero. 


int OpenSound( ) 


This function accesses the play device and prevents it from being opened subsequently by 
other applications. 


This function has no parameters. 


The return value specifies the number of voices available. The return value is 
S_SERDVNA if the play device is in use, and S_SEROFM if insufficient memory is avail- 
able. 


OutputDebugString 


Syntax 


Return Value 


Comments 


void OutputDebugString(/pOutputString) 


This function sends a debugging message to the debugger if present, or to the auxiliary 
(AUX) device if the debugger is not present. 


Parameter Type/Description 
[pOutputString LPSTR Points to a null-terminated string. 


None. 


This function preserves all registers. It is available only in the debugging version of 


_ Windows. 
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PaintRgn 


PaintRgn 
Syntax 


Return Value 


BOOL PaintRgen(iDC, hRgn) 


This function fills the region specified by the hRgn parameter with the selected brush. 


Parameter Type/Description 
hDC HDC Identifies the device context that contains the region. 
hRgn HRGN Identifies the region to be filled. The coordinates for the 


given region are specified in device units. 


The return value specifies the outcome of the function. It is nonzero if the function is 
successful. Otherwise, it is zero. 


PALETTEINDEX 


Syntax 


Return Value 


COLORREF PALETTEINDEX(nPaletteIndex) 


This macro accepts an index to a logical color palette entry and returns a value consisting 
of 1 in the high-order byte and the palette entry index in the low-order bytes. This is called 
a palette-entry specifier. An application using a color palette can pass this specifier instead 
of an explicit RGB value to functions that expect a color. This allows the function to use 
the color in the specified palette entry. 


Parameter Type/Description 


nPaletteIndex int Specifies an index to the palette entry containing the color 
to be used for a graphics operation. 


The return value is a logical-palette index specifier. When using a logical palette, an appli- 
cation can use this specifier in place of an explicit RGB value for GDI functions that re- 
quire a color. 


PALETTERGB 


Syntax 


COLORREF PALETTERGB(cRed, cGreen, cBlue) 


This macro accepts three values representing relative intensities of red, green, and blue, 
and returns a value consisting of 2 in the high-order byte and an RGB value in the three 
low-order bytes. This is called a palette-relative RGB specifier. An application using a 


PatBit 
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Return Value 


PatBit 
Syntax 


color palette can pass this specifier instead of an explicit RGB value to functions that ex- 
pect a color. 


For output devices that support logical palettes, Windows matches a palette-relative RGB 
value to the nearest color in the logical palette of the device context, as though the applica- 
tion had specified an index to that palette entry. If an output device does not support a sys- 
tem palette, then Windows uses the palette-relative RGB as though it were a conventional 
RGB DWORD returned by the RGB macro. 


Parameter § ‘ Type/Description 

cRed BYTE Specifies the intensity of the red color field. 
cGreen BYTE Specifies the intensity of the green color field. 
cBlue . BYTE Specifies the intensity of the blue color field. 


The return value specifies a palette-relative RGB value. 


BOOL PatBIt(DC, X, Y, nWidth, nHeight, dwRop) 


This function creates a bit pattern on the specified device. The pattern is a combination of 
the selected brush and the pattern already on the device. The raster-operation code 
specified by the dwRop parameter defines how the patterns are to be combined. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
x int Specifies the logical x-coordinate of the upper-left corner of the 


rectangle that is to receive the pattern. 


Y int Specifies the logical y-coordinate of the upper-left corner of the 
rectangle that is to receive the pattern. 


nWidth int Specifies the width (in logical units) of the rectangle that is to 
receive the pattern. 


nHeight int Specifies the height (in logical units) of the rectangle that is to 
receive the pattern. 


4-329 


PeekMessage 


Return Value 


Comments 


PeekMessage 
Syntax 


Parameter Type/Description 


dwRop DWORD _ Specifies the raster-operation code. Raster-operation 
codes (ROPs) define how GDI combines colors in output operations 
that involve a current brush, a possible source bitmap, and a destina- 
tion bitmap. For a list of the raster-operation codes, see Table 4.12, 
“Raster Operations.” 


The return value specifies the outcome of the function. It is nonzero if the bit pattern is 
drawn. Otherwise, it is zero. 


The values of dwRop for this function are a limited subset of the full 256 ternary raster- 
operation codes; in particular, an operation code that refers to a source cannot be used. 


Not all devices support the PatBIt function. For more information, see the RC_BITBLT 
capability in the GetDeviceCaps function, earlier inthis chapter. 


Table 4.12 lists the various raster-operation codes for the dwRop parameter: 


Table 4.12 Raster Operations 


Code Description 

PATCOPY Copies pattern to destination bitmap. 

PATINVERT Combines destination bitmap with pattern using the Boolean 
OR operator. 

DSTINVERT Inverts the destination bitmap. 

BLACKNESS Turns all output black. 

WHITENESS Tums all output white. 


BOOL  PeekMessage(/pMsg, hWnd, wMsgFilterMin, wMsgFilterMax, wRemoveMsg) 


This function checks the application queue for a message and places the message (if any) 
in the data structure pointed to by the JpMsg parameter. Unlike the GetMessage function, 
the PeekMessage function does not wait for a message to be placed in the queue before re- 
turning. It does, however, yield control (if the PM_NOYIELD flag isn’t set) and does not 
return control after the yield until Windows returns control to the application. 


PeekMessage retrieves only messages associated with the window specified by the hWnd 
parameter, or any of its children as specified by the IsChild function, and within the range 
of message values given by the wMsgFilterMin and wMsgFilterMax parameters. If hWnd 
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Return Value 


Comments 


is NULL, PeekMessage retrieves messages for any window that belongs to the application 
making the call. (The PeekMessage function does not retrieve messages for windows that 
belong to other applications.) If hWnd is -1, PeekMessage returns only messages with a 
hWnd of NULL as posted by the PostAppMessage function. If wMsgFilterMin and 
wMsgFilterMax are both zero, PeekMessage returns all available messages (no range fil- 
tering is performed). 


The WM_KEYFIRST and WM_KEYLAST flags can be used as filter values to retrieve all 
key messages; the WM_MOUSEFIRST and WM_MOUSELAST flags can be used to re- 
trieve all mouse messages. 


Parameter Type/Description 

IpMsg LPMSG Points to an MSG data structure that contains 
message information from the Windows application queue. 

hWnd HWND Identifies the window whose messages are to be ex- 
amined. 

wMsgFilterMin WORD Specifies the value of the lowest message position to 


be examined. 


wMsgFilterMax WORD Specifies the value of the highest message position to. 
be examined. 


wRemoveMsg WORD Specifies a combination of the flags described in the 
following list. PM_NOYIELD can be combined with either 
PM_NOREMOVE or PM_REMOVE: 


Value Meaning 


PM_NOREMOVE Messages are not removed from the 
queue after processing by PeekMessage. 


PM_NOYIELD Prevents the current task from halting 
: and yielding system resources to another 
task. 
PM_REMOVE Messages are removed from the queue 


after processing by PeekMessage. 


The return value specifies whether or not a message is found. It is nonzero if a message is 
available. Otherwise, it is zero. 


PeekMessage does not remove WM_PAINT messages from the queue. The messages re- 
main in the queue until processed. The GetMessage, PeekMessage, and WaitMessage 
functions yield control to other applications. These calls are the only way to let other 
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Pie 


Pie 
Syntax 


applications run. If your application does not call any of these functions for long periods of 
time, other applications cannot run. 


When GetMessage, PeekMessage, and WaitMessage yield control to other applications, 
the stack and data segments of the application calling the function may move in memory to 
accommodate the changing memory requirements of other applications. 


If the application has stored long pointers to objects in the data or stack segment (global or 
local variables), and if they are unlocked, these pointers can become invalid after a call to 
GetMessage, PeekMessage, or WaitMessage. The /pMsg parameter of the called function 
remains valid in any case. 


BOOL  Pie(hDC, X1, Y1, X2, Y2, X3, Y3, X4, Y4) 


This function draws a pie-shaped wedge by drawing an elliptical arc whose center and two 
endpoints are joined by lines. The center of the arc is the center of the bounding rectangle 
specified by the X/, YJ, X2, and Y2 parameters. The starting and ending points of the arc 
are specified by the X3, Y3, X4, and Y4 parameters. The arc is drawn with the.selected pen, 
moving in a counterclockwise direction. Two additional lines are drawn from each end- 
point to the arc’s center. The pie-shaped area is filled with the selected brush. 


If X3 equals X4 and Y3 equals Y4, the result is an ellipse with a single line from the center 
of the ellipse to the point (X3, Y3), or (X4, Y4). 


Parameter Type/Description 
hDC HDC Identifies the device context. 
Xl int Specifies the logical x-coordinate of the upper-left corner of the 


bounding rectangle. 


Yl int Specifies the logical y-coordinate of the upper-left corner of the 
' bounding rectangle. 


X2 int Specifies the logical x-coordinate of the lower-right corner of 
the bounding rectangle. 


¥2 int Specifies the logical y-coordinate of the lower-right corner of 
the bounding rectangle. 


X3 int Specifies the logical x-coordinate of the starting point of the 
arc. This point does not have to lie exactly on the arc. 


Y3 int Specifies the logical y-coordinate of the starting point of the 
arc. This point does not have to lie exactly on the arc. 
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Parameter Type/Description 
x4 int Specifies the logical x-coordinate of the endpoint of the arc. 
This point does not have to lie exactly on the arc. 
Y4 int Specifies the logical y-coordinate of the endpoint of the arc. 


Return Value 


Comments 


PlayMetaFile 
Syntax 


Return Value 


This point does not have to lie exactly on the arc. 


The return value specifies whether or not the pie shape is drawn. It is nonzero if the pie 
shape is drawn. Otherwise, it is zero. 


The width of the rectangle, specified by the absolute value of X2 — X/, must not exceed 
32,767 units. This limit applies to the height of the rectangle as well. 


The current position is neither used nor updated by this function. 


BOOL PlayMetaFile(ADC, hMF) 


This function plays the contents of the specified metafile on the given device. The metafile 
can be played any number of times. 


Parameter Type/Description 
hDC HDC Identifies the device context of the output device. 
hMF HANDLE Identifies the metafile. 


The return value specifies the outcome of the function. It is nonzero if the function is 
successful. Otherwise, it is zero. 


PlayMetaFileRecord 


Syntax 


void PlayMetaFileRecord(hDC, lpHandletable, lpMetaRecord, nHandles) 


This function plays a metafile record by executing the GDI function call contained within 
the metafile record. 
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Polygon 


Return Value 


Comments 


Polygon 
Syntax 


Return Value 


Comments 


Parameter Type/Description 
hDC HDC Identifies the device context of the output device. 


IpHandletable LPHANDLETABLE Points to the object handle table to be 
used for the metafile playback. 


IpMetaRecord LPMETARECORD Points to the metafile to be played. 
nHandles WORD _ Specifies the number of handles in the handle table. 


None. 


An application typically uses this function in conjunction with the EnumMetafile function 
to modify and then play a metafile. 


BOOL Polygon(hDC, IpPoints, nCount) 


This function draws a polygon consisting of two or more points (vertices) connected by 
lines. The polygons are filled using the current polygon-filling mode. For a description of 
the polygon-filling mode, see the SetPolyFillMode function, later in this chapter. The poly- 
gon is automatically closed, if necessary, by drawing d line from the last vertex to the first. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpPoints LPPOINT Points to an array of points that specify the vertices of 


the polygon. Each point in the array is a POINT data structure. 


nCount int Specifies the number of vertices given in the array. 


The return value specifies the outcome of the function. It is nonzero if the function is 
successful. Otherwise, it is zero. 
The current position is neither used nor updated by this function. 


The current polygon-filling mode can be retrieved or set by using the GetPolyFillMode 
and SetPolyFillMode functions. 
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Polyline 
Syntax BOOL  Polyline(iDC, [pPoints, nCount) 
This function draws a set of line segments, connecting the points specified by the /pPoints 
parameter. The lines are drawn from the first point through subsequent points with the 
result as if the MoveTo and LineTo functions were used to move to each new point and 
then connect it to the next. However, the current position is neither used nor updated by 
the Polyline function. 
Parameter Type/Description 
hDC HDC Identifies the device context. 
IpPoints LPPOINT Points to an array of points to be connected. Each point 
in the array is a POINT data structure. 
nCount int Specifies the number of points in the array. The nCount parame- 
ter must be at least 2. 
Return Value The return value specifies whether or not the line segments were drawn. It is nonzero if the 
line segments were drawn. Otherwise, it is zero. 
Comments This function draws lines with the selected pen. 


PolyPolygon 
Syntax BOOL  PolyPolygon(hDC, lpPoints, lpPolyCounts, nCount) 


This function creates a series of closed polygons. The polygons are filled using the current 
polygon-filling mode. For a description of the polygon-filling mode, see the SetPolyFill- 
Mode function, later in this chapter. The polygons may overlap, but they do not have to 


overlap. 

Parameter Description . 

hDC HDC Identifies the device context. 

[pPoints LPPOINT Points to an array of POINT data structures that define 


the vertices of the polygons. Each polygon must be a closed polygon. 
Unlike polygons created by the Polygon function, the polygons . 
created by PolyPolygon are not automatically closed. The polygons 
are specified consecutively. 
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PostAppMessage 


Return Value 


Parameter Description 


lpPolyCounts LPINT Points to an array of integers, each of which specifies the 
number of points in one of the polygons in the /pPoints array. 


nCount int Specifies the total number of integers in the /pPolyCounts 
array. 


The return value specifies the outcome of the function. It is nonzero if the polygons were 
drawn. Otherwise, it is zero. 


PostAppMessage 


Syntax 


Return Value 


PostMessage 
Syntax 


BOOL PostAppMessage(hTask, wMsg, wParam, lParam) 


This function posts a message to an application identified by a task handle, and then re- 
turns without waiting for the application to process the message. The application receiving 
the message obtains the message by calling the GetMessage or PeekMessage function. 
The hWnd parameter of the returned MSG structure is NULL. 


Parameter Type/Description 

hTask HANDLE Identifies the task that is to receive the message. The 
GetCurrentTask function returns this handle. 

wMsg WORD Specifies the type of message posted. 

wParam WORD _ Specifies additional message information. 

[Param DWORD Specifies additional message information. 


The return value specifies whether or not the message is posted. It is nonzero if the 
message is posted. Otherwise, it is zero. 


BOOL _ PostMessage(hWnd, wMsg, wParam, [Param) 


This function places a message in a window’s application queue, and then returns without 
waiting for the corresponding window to process the message. The posted message can be 
retrieved by calls to the GetMessage or PeekMessage function. 
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Return Value 


Comments 


Parameter Type/Description 


hWnd HWND Identifies the window to receive the message. If the 
hWnd parameter is OxFFFF, the message is sent to all overlapped 
or pop-up windows in the system. The message is not sent to 
child windows. 


wMsg WORD Specifies the type of message posted. 
wParam WORD Specifies additional message information. 
lParam DWORD _ Specifies additional message information. 


The return value specifies whether or not the message is posted. It is nonzero if the 
message is posted. Otherwise, it is zero. 


An application should never use the PostMessage function to send a message to a control. 
If a system running Windows is configured for an expanded-memory system (EMS) and 
an application sends a message (by using the PostMessage function) with related data 
(that are pointed to by the /Param parameter) to a second application, the first application 
must place the data (that /Param points to) in global memory allocated with the GlobalAI- 
loc function and the GMEM_LOWER flag. Note that this allocation of memory is neces- 
sary only if /Param contains a pointer. 


Unlike other Windows functions, an application may call PostMessage at the hardware- 
interrupt level. 


PostQuitMessage 


Syntax 


void PostQuitMessage(nExitCode) 


This function informs Windows that the application wishes to terminate execution. It is 
typically used in response toa WM_DESTROY message. 


The PostQuitMessage function posts a WM_QUIT message to the application and returns 
immediately; the function merely informs the system that the application wants to quit 
sometime in the future. 


When the application receives the WM_QUIT message, it should exit the message loop in 
the main function and return control to Windows. The exit code returned to Windows must 
be the wParam parameter of the WM_QUIT message. 
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ProfClear 


Return Value 


ProfClear 


Syntax 


Return Value 


Parameter Type/Description 


nExitCode int Specifies an application exit code. It is used as the 
wParam parameter of the WM_QUIT message. 


None. 


void ProfClear() 


When running the Microsoft Windows Profiler, this function discards all samples currently 
in the sampling buffer. See Jools for more information on using the Profiler. 


This function has no parameters. 


None. 


ProfFinish 


Syntax 


Return Value 


void ProfFinish() 


When running the Microsoft Windows Profiler, this function stops sampling and flushes 
the output buffer to disk. 


When running with Windows in 386 enhanced mode, ProfFinish also frees the buffer for 
system use. See Tools for more information on using the Profiler. 


This function has no parameters. 


None. 


ProfFlush 


Syntax 


void ProfFlush( ) 


When running the Microsoft Windows Profiler, this function flushes the sampling buffer to 
disk, provided that samples do not exceed predefined limits. 


When running with Windows in any mode other than 386 enhanced mode, you must 
specify the size of the output buffer and the amount of samples to be written to disk. 


ProfinsChk 
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Return Value 


Comments 


When running with Windows in 386 enhanced mode, an application calls the ProfSetup 
function to specify the size of the output buffer and the amount of samples to be written to 


_ disk. 


See Jools for more information on using the Profiler. 


This function has no parameters. 
None. 


Do not call ProfFlush repeatedly because it can seriously impair the performance of the 
application. Additionally, do not call the function when DOS may be unstable, as in inter- 
rupt handling. 


ProflnsChk 


Syntax 


Return Value 


«  ProfSampRate 
e Syntax 


int ProfInsChk() 


This function determines if the Microsoft Windows Profiler is installed. See Tools for more 
information on using the Profiler. 


This function has no parameters. 


The return value specifies whether Profiler is installed and the version installed. The return - 
value is zero if Profiler is not installed, 1 if the Windows Profiler is installed for a mode 
other than 386 enhanced mode, and 2 if the Windows 386 enhanced mode Profiler is in- 
stalled. 


void ProfSampRate(nRate286, nRate386) 


When running the Microsoft Windows Profiler, this function sets the rate of code sam- 
pling. See Tools for more information on using the Profiler. 


Parameter Type/Description 


nRate286 int Specifies the sampling rate of Profiler if the application is 
running with Windows in any mode other than 386 enhanced 
mode. The value of nRate286 ranges from 1 to 13, indicating the 
following sampling rates: 
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Parameter_ Type/Description 
Value’ Sampling Rate 
1 122.070 microseconds 
2 244.141 microseconds 
3 488.281 microseconds 
4 976.562 microseconds 
5 1.953125 milliseconds 
6 3.90625 milliseconds 
7 7.8125 milliseconds 
8 15.625 milliseconds 
9 31.25 milliseconds 
10 62.5 milliseconds 
11 125 milliseconds 
12 250 milliseconds 
13 500 milliseconds 
nRate386 int Specifies the sampling rate of Profiler if the application is 

running with Windows in 386 enhanced mode. The value of 
nRate386 can range from 1 to 1000, specifying the sampling rate 
in milliseconds. 

Return Value None. 

Comments The default rate is 5 (1.953125 milliseconds) for Windows in any mode other than 386 en- 


hanced mode. The default rate is 2 milliseconds for Windows in 386 enhanced mode. 


Profiler only selects the parameter appropriate for the version of Windows being used. 


ProfSetup | 


Syntax void ProfSetup(nBufferSize, nSamples) 


When running the Microsoft Windows Profiler with Windows in 386 enhanced mode, this 
function specifies the size of the output buffer and the amount of samples written to disk. 
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Profiler ignores the ProfSetup function when running with Windows in any mode other 
than 386 enhanced mode. See Jools for more information on using the Profiler. 


Parameter Type/Description 


nBufferSize int Specifies the size of the output buffer in kilobytes. The 
nBufferSize parameter can range from 1 to 1064. The default is 
64. 


nSamples int Specifies how much sampling data Profiler writes to disk. 
A value of zero specifies unlimited sampling data. The default is 
zero. 


ProfStart 


Syntax void ProfStart() 


When running the Microsoft Windows Profiler, this function starts sampling. See Tools for 
more information on using the Profiler. 


This function has no parameters. 


Return Value None. 


ProfStop 


Syntax void ProfStop() 


When running the Microsoft Windows Profiler, this function stops sampling. See Tools for 
more information on using the Profiler. © 


This function has no parameters. 


Return Value None. 
PtinRect 
Syntax BOOL  PtInRect(/pRect, Point) 


This function specifies whether the specified point lies within a given rectangle. A point is 
' within a rectangle if it lies on the left or top side, or is within all four sides. A point on the 
right or bottom side is outside the rectangle. 


« 
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PtinRegion 


Return Value 


PtinRegion 
Syntax 


Return Value 


PiVisible 
Syntax 


Parameter Type/Description 

IpRect LPRECT Points toa RECT data structure that contains the 
specified rectangle. 

Point POINT = Specifies a POINT data structure that contains the 
specified point. 


The return value specifies whether the specified point lies within the given rectangle. It is 
nonzero if the point lies within the given rectangle. Otherwise, it is zero. 


BOOL  PtInRegion(hRegn, X, Y) 


This function specifies whether the point given by the X and Y parameters is in the given 
region. 


Parameter Type/Description 

hRgn HRGN _Identifies the region to be examined. 

Xx int Specifies the logical x-coordinate of the point. 
Y int Specifies the logical y-coordinate of the point. 


The return value specifies whether the specified point is in the given region. It is nonzero 
if the point is in the region. Otherwise, it is zero. . 


BOOL  PtVisible(hDC, x, Y) 


This function specifies whether the given point is within the clipping region of the 
specified device context. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
Xx int Specifies the logical x-coordinate of the point. 


Y int Specifies the logical y-coordinate of the point. 


es WEm nA : 


PtVisible 


Return Value 
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The return value specifies whether the specified point is within the clipping region of the 
given display context. It is nonzero if the point is within the clipping region. Otherwise, it 
is Zero. 
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ReadComm 
Syntax 


Return Value 


RealizePalette 
Syntax. 


int - ReadComm(nCid, [pBuf, nSize) 


This function reads the number of characters specified by the nSize parameter from the 
communication device specified by the nCid parameter and copies the characters into the 
buffer pointed to by the /pBuf parameter. 


Parameter Type/Description 

nCid int Specifies the communication device to be read. The Open- 
Comm function returns this value. 

IpBuf LPSTR _ Points to the buffer that is to receive the characters read. 

nSize int Specifies the number of characters to be read. 


The return value specifies the number of characters actually read. It is less than the number 
specified by nSize only if the number of characters in the receive queue is less than that 
specified by nSize. If it is equal to nSize, additional characters may be queued for the 
device. If the return value is zero, no characters are present. 


When an error occurs, the return value is set to a value less than zero, with the absolute 
value being the actual number of characters read. The cause of the error can be determined 
by using the GetCommError function to retrieve the error code and status. Since errors 
can occur when no bytes are present, if the return value is zero, the GetCommError func- 
tion should be used to ensure that no error occurred. 


For parallel I/O ports, the return value will always be zero. 


int RealizePalette(hDC) 


This function maps to the system palette entries in the logical palette currently selected 
into a device context. 


A logical color palette acts as a buffer between color-intensive applications and the system, 
allowing an application to use as many colors as needed without interfering with its own 
color display, or with colors displayed by other windows. When a window has input focus 
and calls RealizePalette, Windows ensures that it will display all the colors it requests, up 
to the maximum number simultaneously available on the display, and displays additional 
colors by matching them to available colors. In addition, Windows matches the colors re- 
quested by inactive windows that call RealizePalette as closely as possible to the available 
colors. This significantly reduces undesirable changes in the colors displayed in inactive 
windows. 
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Parameter Type/Description 
hDC HDC Identifies the device context. 
Return Value The return value specifies how many entries in the logical palette were mapped to different 


entries in the system palette. This represents the number of entries which this function re- 
mapped to accommodate changes in the system palette since the logical palette was last re- 


alized. 
Rectangle 
Syntax BOOL §Rectangle(iDC, X/, Y1, X2, Y2) 
This function draws a rectangle. The interior of the rectangle is filled by using the selected 
brush, and a border is drawn with the selected pen. 
Parameter Type/Description 
hDC ' HDC Identifies the device context. 
Xl int Specifies the logical x-coordinate of the upper-left corner of the 
rectangle. 
Yl int Specifies the logical y-coordinate of the upper-left corner of the 
rectangle. . 
X2 int Specifies the logical x-coordinate of the lower-right corner of 
the rectangle. 
y2 int Specifies the logical y-coordinate of the lower-right corner of 
the rectangle. 
Return Value The return value specifies whether the rectangle is drawn. It is nonzero if the rectangle is 
drawn. Otherwise, it is zero. 
Comments The width of the rectangle specified by the X/, Y/, X2, and Y2 parameters must not exceed 


32,767 units. This limit applies to the height of the rectangle as well. 


The current position is neither used nor updated by this function. 
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RectinRegion 


RectinRegion 


Syntax 


Return Value 


RectVisible 
Syntax 


Return Value 


RegisterClass 
Syntax 


BOOL RectInRegion(hRegion, IpRect) 


This function determines whether any part of the rectangle specified by the /pRect parame- 
ter is within the boundaries of the region identified by the hRegion parameter. 


Parameter Type/Description 
hRegion HRGN Identifies the region. 
IpRect LPRECT _ Identifies the rectangle. 


The return value is TRUE if any part of the specified rectangle lies within the boundaries 
of the region. Otherwise, the return value is FALSE. 


BOOL RectVisible(hDC, [pRect) 


This function determines whether any part of the given rectangle lies within the clipping re- 
gion of the specified display context. 


Parameter Type/Description 
hDC HDC Identifies the device context. 


IpRect LPRECT Points toa RECT data structure that contains the logi- 
cal coordinates of the specified rectangle. 


The return value specifies whether the rectangle is within the clipping region. It is nonzero 
if some portion of the given rectangle lies within the clipping region. Otherwise, it is zero. 


BOOL RegisterClass(/pWndClass) 


This function registers a window class for subsequent use in calls to the CreateWindow 
function. The window class has the attributes defined by the contents of the data structure 
pointed to by the JpWndClass parameter. If two classes with the same name are registered, 
the second attempt fails and the information for that class is ignored. 
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Parameter Type/Description 


lpWndClass LPWNDCLASS Points toa WNDCLASS data structure. The 
structure must be filled with the appropriate class attributes before 
being passed to the function. See the following “Comments” section 
for details. 


Return Value The return value specifies whether the window class is registered. It is nonzero if the class 
is registered. Otherwise, it is zero. 


Comments The callback function must use the Pascal calling conventions and must be declared FAR. 


Callback Function BOOL FAR PASCAL WnhaProc(hWnd, wMsg, wParam, lParam) 
HWND hWnd; 
WORD wMszg; 
WORD wParam; 
DWORD /Param; 


WndProc is a placeholder for the application-supplied function name. The actual name 
must be exported by including it in an EXPORTS statement in the application’s module- 
definition file. 


Parameter Description 

hWnd Identifies the window that receives the message. 
wMsg Specifies the message number. | 

wParam Specifies additional message-dependent information. 
[Param Specifies additional message-dependent information. 


Return Value 


The window function returns the result of the message processing. The possible return 
values depend on the actual message sent. 


RegisterClipboardFormat 
Syntax WORD RegisterClipboardFormat(/pFormatName) 


This function registers a new clipboard format whose name is pointed to by the /pFormat- 
Name parameter. The registered format can be used in subsequent clipboard functions as a 
valid format in which to render data, and it will appear in the clipboard’s list of formats. 
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RegisterWindowMessage 


Return Value 


Comments 


Parameter Type/Description 


lpFormatName LPSTR Points to a character string that names the new for- 
. mat. The string must be a null-terminated character string. 


The return value specifies the newly registered format. If the identical format name has 
been registered before, even by a different application, the format’s reference count is in- 
creased and the same value is returned as when the format was originally registered. The 
return value is zero if the format cannot be registered. 


The format value returned by the RegisterClipboardFormat function is within the range 
of OxC000 to OxXFFFF. 


RegisterWindowMessage 


Syntax 


Return Value 


Comments 


WORD = RegisterWindowMessage(/pString) 


This function defines a new window message that is guaranteed to be unique throughout 
the system. The returned message value can be used when calling the SendMessage or 
PostMessage function. 


RegisterWindowMessage is typically used for communication between two cooperating 
applications. . 


If the same message string is registered by two different applications, the same message 
value is returned. The message remains registered until the user ends the Windows session. 
Parameter Type/Description 


IpString LPSTR Points to the message string to be registered. 


The return value specifies the outcome of the function. It is an unsigned short integer 
within the range OxC000 to OxFFFF if the message is successfully registered. Otherwise, it 
is Zero. . 


Use the Register WindowMessage function only when the same message must be under- 
stood by more than one application. For sending private messages within an application, 
an application can use any integer within the range WM_USER to OxBFFF. 
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ReleaseCapture 
Syntax void ReleaseCapture( ) 


This function releases the mouse capture and restores normal input processing. A window 
with the mouse capture receives all mouse input regardless of the position of the cursor. 


This function has no parameters. 


Return Value None. 

Comments An application calls this function after calling the SetCapture function. 
ReleaseDC 

Syntax int ReleaseDC(hWnd, hDC) 


This function releases a device context, freeing it for use by other applications. The effect 
of the ReleaseDC function depends on the device-context type. It only frees common and 
window device contexts. It has no effect on class or private device contexts. 


Parameter Type/Description 
hWnd HWND _Identifies the window whose device context is to be 
released. 
hDC HDC _ Identifies the device context to be released. 
Return Value The return value specifies whether the device context is released. It is 1 if the device con- 


text is released. Otherwise, it is zero. 


Comments The application must call the ReleaseDC function for each call to the GetWindowDC 
function and for each call to the GetDC function that retrieves a common device context. 


RemoveFontResource 
Syntax BOOL  RemoveFontResource(lpFilename) 


This function removes an added font resource from the file named by the [pFilename para- 
meter or from the Windows font table. 
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Parameter Type/Description 


lpFilename LPSTR Points to a string that names the font-resource file or con- 
tains a handle to a loaded module. If [pF ilename points to the 
font-resource filename, the string must be null-terminated and have 
the DOS filename format. If [pFilename contains a handle, the 
handle must be in the low-order word; the high-order word must be 
zero. 


Return Value The return value specifies the outcome of the function. It is nonzero if the function is 
successful. Otherwise, it is zero. 


Comments Any application that adds or removes fonts from the Windows font table should notify 
. other windows of the change by using the SendMessage function with the hWnd parame- 
ter set to—1 to send a WM_FONTCHANGE message to all top-level windows in the sys- 
tem. 


The RemoveFontResource function may not actually remove the font resource. If there 
are outstanding references to the resource, the font resource remains loaded until the last 
referencing logical font has been deleted by using the DeleteObject function. 


RemoveMenu 
Syntax BOOL RemoveMenu(hMenu, nPosition, wFlags) 


This function deletes an menu item with an associated pop-up menu from the menu iden- 
tified by the hMenu parameter but does not destroy the handle for the pop-up menu, allow- 
ing the menu to be reused. Before calling this function, the application should call 
GetSubMenu to retrieve the pop-up menu handle. 


Parameter Type/Description 
hMenu HMENU Identifies the menu to be changed. 
nPosition WORD _ Specifies the menu item to be removed. The interpretation 


of the nPosition parameter depends upon the setting of the wFlags 
parameter. 
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Return Value 


Comments 


RemoveProp 
Syntax 


Return Value 


Parameter Type/Description 
If wFlags is nPosition 
MF_BYCOMMAND Specifies the command ID of the ex- 
isting menu item. 
MF_BYPOSITION Specifies the position of the menu 
item. The first item in the menu is at 
position zero. 
wFlags WORD Specifies how the nPosition parameter is interpreted. It 


must be either MF_BYCOMMAND or MF_BYPOSITION. 


The return value specifies the outcome of the function. It is TRUE if the function is 
successful. Otherwise, it is FALSE. 


Whenever a menu changes (whether or not the menu resides in a window that is dis- 
played), the application should call DrawMenuBar. 


HANDLE RemoveProp(hWnd, IpString) 


This function removes an entry from the property list of the specified window. The 
character string specified by the /pString parameter identifies the entry to be removed. 


The RemoveProp function returns the data handle associated with the string so that the 
application can free the data associated with the handle. 


Parameter Type/Description 

hWnd ~HWND Identifies the window whose property list is to be 
changed. 

IpString LPSTR Points to a null-terminated character string or to an atom 


that identifies a string. If an atom is given, it must have been pre- 
viously created by means of the AddAtom function. The atom, a 
16-bit value, must be placed in the low-order word of /pString; the 
high-order word must be zero. 


The return value identifies the given string. It is NULL if the string cannot be found in the 
given property list. 
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ReplyMessage 


Comments 


ReplyMessage 
Syntax 


Return Value 


An application must free the data handles associated with entries removed from a property 
list. The application should only remove those properties which it added to the property 
list. 


void ReplyMessage(/Reply) 


This function is used to reply to a message sent through the SendMessage function 
without returning control to the function that called SendMessage. 


By calling this function, the window function that receives the message allows the task 
that called SendMessage to continue to execute as though the task that received the 
message had returned control. The task that calls ReplyMessage also continues to execute. 


Normally a task that calls SendMessage to send a message to another task will not con- 
tinue executing until the window procedure that Windows calls to receive the message re- 
turns. However, if a task that is called to receive a message needs to perform some type of 
operation that might yield control (such as calling the MessageBox or DialogBox func- 
tions), Windows could be placed in a deadlock situation where the sending task needs to 
execute and process messages but cannot because it is waiting for SendMessage to return. 
An application can avoid this problem if the task receiving the message calls ReplyMes- 
sage before performing any operation that could cause the task to yield. 


The Reply Message function has no effect if the message was not sent through the Send- 
Message function or if the message was sent by the same task. 


Parameter Type/Description 


IReply LONG _ Specifies the result of the message processing. The 
possible values depend on the actual message sent. 


None. 


ResizePalette 


Syntax 


BOOL ResizePalette(hPalette, nNumEntries) 


This function changes the size of the logical palette specified by the hPalette parameter to 
the number of entries specified by the nNumEntries parameter. If an application calls Re- 
sizePalette to reduce the size of the palette, the entries remaining in the resized palette are 
unchanged. If the application calls ResizePalette to enlarge the palette, the additional 
palette entries are set to black (the red, green, and blue values are all 0) and the flags for all 
additional entries are set to 0. 
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Parameter Type/Description 
hPalette HPALETTE Identifies the palette to be changed. 
nNumEntries int Specifies the number of entries in the palette after it has been re- 
sized. 


Return Value 


RestoreDC 
Syntax 


Return Value 


NET 


RGB 
Syntax 


The return value specifies the outcome of the function. It is TRUE if the palette was 
successfully resized. Otherwise, it is FALSE. 


BOOL RestoreDC(hDC, nSavedDC) 


This function restores the device context specified by the hDC parameter to the previous 
state identified by the nSavedDC parameter. The RestoreDC function restores the device 
context by copying state information saved on the context stack by earlier calls to the 
SaveDC function. 


The context stack can contain the state information for several device contexts. If the con- 
text specified by nSavedDC is not at the top of the stack, RestoreDC deletes any state 
information between the device context specified by the nSavedDC parameter and the top 
of the stack. The deleted information is lost. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
nSavedDC int Specifies the device context to be restored. It can be a value re- 


tured by a previous SaveDC function call. If nSavedDC is -1, the 
most recent device context saved is restored. 


The return value specifies the outcome of the function. It is TRUE if the specified context 
was restored. Otherwise, it is FALSE. 


COLORREF RGB(cRed, cGreen, cBlue) 


This macro selects an RGB color based on the parameters supplied and the color capabili- 
ties of the output device. 
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Return Value 


Comments 


RoundRect 
Syntax 


RoundRect 


Parameter Type/Description 

cRed BYTE Specifies the intensity of the red color field. 
cGreen BYTE Specifies the intensity of the green color field. 
cBlue BYTE Specifies the intensity of the blue color field. 


The return value specifies the resultant RGB color. 


The intensity for each argument can range from 0 to 255. If all three intensities are 
specified as 0, the result is black. If all three intensities are specified as 255, the result is 
white. 


For information on using color values in a color palette, see the descriptions of the 
PALETTEINDEX and PALETTERGB macros, earlier in this chapter. 


BOOL  RoundRect(hDC, X1, Y1, X2, Y2, X3, Y3) 


This function draws a rectangle with rounded corners. The interior of the rectangle is filled 
by using the selected brush, and a border is drawn with the selected pen. 


Parameter Type/Description | 

hDC HDC Identifies the device context. 

X1 int Specifies the logical x-coordinate of the upper-left corner of the 

. rectangle. 

Yl int Specifies the logical y-coordinate of the upper-left corner of the 
rectangle. 

X2 int Specifies the logical x-coordinate of the lower-right corner of 
the rectangle. 

Y2 int Specifies the logical y-coordinate of the lower-right corner of 
the rectangle. 

X3 int Specifies the width of the ellipse used to draw the rounded 
comers. 

Y3 int Specifies the height of the ellipse used to draw the rounded 


comers. 


Wen : 
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Return Value The return value specifies whether the rectangle is drawn. It is nonzero if the rectangle is 
drawn. Otherwise, it is zero. 


Comments The width of the rectangle specified by the X/, Y/, X2, and Y2 parameters must not exceed 
32,767 units. This limit applies to the height of the rectangle as well. 


The current position is neither used nor updated by this function. 
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SaveDC 


SaveDC 
Syntax 


Return Value 


int SaveDC(ADC) 


This function saves the current state of the device context specified by the hDC parameter 
by copying state information (such as clipping region, selected objects, and mapping 
mode) to a context stack. The saved device context can later be restored by using the 
RestoreDC function. 


Parameter Type/Description 


hDC HDC Identifies the device context to be saved. 


The return value specifies the saved device context. It is zero if an error occurs. 


Comments The SaveDC function can be used any number of times to save any number of device- 
context states. 

ScaleViewportExt 

Syntax DWORD  ScaleViewportExt(hDC, Xnum, Xdenom, Ynum, Ydenom) 


Return Value 


This function modifies the viewport extents relative to the current values. The formulas are 
written as follows: 


XNewVE = (xOIdVE x Xnum)/ X denom 
yNewVE = (yOIdVE x Ynum) / Ydenom 


The new extent is calculated by multiplying the current extents by the given numerator and 
then dividing by the given denominator. 


Parameter Type/Description 

hDC HDC Identifies the device context. 

Xnum int Specifies the amount by which to multiply the current x-extent. 
Xdenom int Specifies the amount by which to divide the current x-extent. On 
Ynum int Specifies the amount by which to multiply the current y-extent. , 
Ydenom int Specifies the amount by which to divide the current y-extent. 


The return value specifies the previous viewport extents (in device units). The previous 
y-extent is in the high-order word; the previous x-extent is in the low-order word. 
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ScaleWindowExt 


Syntax 


Return Value 


ScreenToClient 


Syntax 


DWORD = ScaleWindowExt(hDC, Xnum, Xdenom, Ynum, Ydenom) 


This function modifies the window extents relative to the current values. The formulas are 
written as follows: 


xNewWE = (xOIdWE x Xnum) / Xdenom 
yNewWE = (yOIdWE x Ynum) / Ydenom 


The new extent is calculated by multiplying the current extents by the given numerator and 
then dividing by the given denominator. 


Parameter Type/Description 

hDC HDC Identifies the device context. 

Xnum int Specifies the amount by which to multiply the current x-extent. 
Xdenom int Specifies the amount by which to divide the current x-extent. — 
Ynum int Specifies the amount by which to multiply the current y-extent. 
Ydenom int Specifies the amount by which to divide the current y-extent. 


The return value specifies the previous window extents (in logical units). The previous y- 
extent is in the high-order word; the previous x-extent is in the low-order word. 


void ScreenToClient(hWnd, IpPoint) 


This function converts the screen coordinates of a given point on the display to client 
coordinates. The ScreenToClient function uses the window given by the hWnd parameter 
and the screen coordinates given in the POINT data structure pointed to by the /pPoint 
parameter to compute client coordinates, and then replaces the screen coordinates with the 
client coordinates. The new coordinates are relative to the upper-left corner of the given 
window’s client area. 


Parameter Type/Description 


hWnd HWND Identifies the window whose client area will be used for 
the conversion. 


lpPoint LPPOINT Points to a POINT data structure that contains the 
screen coordinates to be converted. 
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ScrolIDC 


Return Value 


Comments 


ScrollDC 
Syntax 


Return Value 


Comments 


None. 


The ScreenToClient formula assumes the given point is in screen coordinates. 


BOOL = ScrollDC(ADC, dx, dy, IprcScroll, lprcClip, hrgnUpdate, lprcUpdate) 


This function scrolls a rectangle of bits horizontally and vertically. The /prcScroll parame- 
ter points to the rectangle to be scrolled, the dx parameter specifies the number of units to 

be scrolled horizontally, and the dy parameter specifies the number of units to be scrolled 

vertically. 


Parameter Type/Description 

hDC HDC Identifies the device context that contains the bits to be 
scrolled. 

dx int Specifies the number of horizontal scroll units. 

dy int Specifies the number of vertical scroll units. 

IpreScroll LPRECT Points to the RECT data structure that contains the 


coordinates of the scrolling rectangle. 


IprcClip LPRECT Points to the RECT data structure that contains the 
coordinates of the clipping rectangle. When this rectangle is smaller 
than the original pointed to by /prcScroll, scrolling occurs only in the 
smaller rectangle. 


hrgnUpdate HRGN Identifies the region uncovered by the scrolling process. 
The ScrolIDC function defines this region; it is not necessarily a 
rectangle. 

lprcUpdate LPRECT Points to the RECT data structure that, upon return, con- 


tains the coordinates of the rectangle that bounds the scrolling update 
region. This is the largest rectangular area that requires repainting. 


This value specifies the outcome of the function. It is nonzero if scrolling is executed. 
Otherwise, it is zero. 


If the JprcUpdate parameter is NULL, Windows does not compute the update rectangle. If 
both the hrgnUpdate and IprcUpdate parameters are NULL, Windows does not compute 
the update region. If hrgnUpdate is not NULL, Windows assumes that it contains a valid 


ScrollWindow 


ScrollWindow 
Syntax 


Return Value 


Comments 
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region handle to the region uncovered by the scrolling process (defined by the ScrolIDC 


function). 


An application should use the Scroll Window function when it is necessary to scroll the en- 


tire client area of a window. Otherwise, it should use ScrolIDC. 


void ScrollWindow(hWnd, XAmount, YAmount, lpRect, lpClipRect) 


This function scrolls a window by moving the contents of the window’s client area the 


number of units specified by the XAmount parameter along the screen’s x-axis and the num- 
ber of-units specified by the YAmount parameter along the y-axis. The scroll moves right if 
XAmount is positive and left if it is negative. The scroll moves down if YAmount is positive 


and up if it is negative. 


Parameter 


hWnd 


XAmount 
YAmount 


IpRect 


IpClipRect 


None. 


If the caret is in the window being scrolled, Scroll Window automatically hides the caret to 


Type/Description 
HWND Identifies the window whose client area is to be scrolled. 


int Specifies the amount (in device units) to scroll in the x direc- 
tion. 


int Specifies the amount (in device units) to scroll in the y direc- 
tion. 


LPRECT Points to a RECT data structure that specifies the por- 
tion of the client area to be scrolled. If JpRect is NULL, the entire 
client area is scrolled. 


LPRECT Points to a RECT data structure that specifies the clip- 
ping rectangle to be scrolled. Only bits inside this rectangle are 
scrolled. If IpClipRect is NULL, the entire window is scrolled. 


prevent it from being erased, then restores the caret after the scroll is finished. The caret 
position is adjusted accordingly. 


The area uncovered by the Scroll Window function is not repainted, but is combined into 
the window’s update region. The application will eventually receive a WM_PAINT 
message notifying it that the region needs repainting. To repaint the uncovered area at the 
same time the scrolling is done, call the Update Window function immediately after cal- 
ling ScrollWindow. 
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SelectClipRgn 


SelectClipRgn 
Syntax 


Return Value 


Comments 


If the /pRect parameter is NULL, the positions of any child windows in the window are off- 
set by the amount specified by XAmount and YAmount, and any invalid (unpainted) areas 
in the window are also offset. ScrollWindow is faster when /pRect is NULL. 


If the /pRect parameter is not NULL, the positions of child windows are not changed, and 
invalid areas in the window are not offset. To prevent updating problems when /pRect is 
not NULL, call the UpdateWindow function to repaint the window before calling 
ScrollWindow. 


int SelectClipRgn(iDC, hRgn) 


This function selects the given region as the current clipping region for the specified 
device context. Only a copy of the selected region is used. The region itself can be selected 
for any number of other device contexts, or it can be deleted. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
hRgn HRGN Identifies the region to be selected. 


The return value specifies the region’s type. It can be any one of the following values: 


Value Meaning 

COMPLEXREGION New clipping region has overlapping borders. 
ERROR Device context or region handle is not valid. 
NULLREGION New clipping region is empty. 
SIMPLEREGION New clipping region has no overlapping borders. 


The SelectClipRgn function assumes that the coordinates for the given region are 
specified in device units. 


Some printer devices support graphics at lower resolutions than text output to increase 
speed, but at the expense of quality. These devices scale coordinates for graphics so that 
one graphics device point corresponds to two or four true device points. This scaling factor 
affects clipping. If a region will be used to clip graphics, its coordinates must be divided 
down by the scaling factor. If the region will be used to clip text, no scaling adjustment is 
needed. The scaling factor is determined by using the GETSCALINGFACTOR printer 
escape. 
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SelectObject 
Syntax 


HANDLE | SelectObject(hDC, hObject) 


This function selects the logical object specified by the hObject parameter as the selected 
object of the specified device context. The new object replaces the previous object of the 
same type. For example, if hObject is the handle to a logical pen, the SelectObject func- 
tion replaces the selected pen with the pen specified by hObject. 


Selected objects are the default objects used by the GDI output functions to draw lines, fill 
interiors, write text, and clip output to specific areas of the device surface. Although a 
device context can have six selected objects (pen, brush, font, bitmap, region, and logical 
palette), no more than one object of any given type can be selected at one time. Select- 
Object does not select a logical palette; to select a logical palette, the application must use 
SelectPalette. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
hObject . HANDLE Identifies the object to be selected. It may be any one of 


the following, and must have been created by using one of the follow- 
ing functions: 


Object Function 

Bitmap (Bitmaps can be CreateBitmap 

selected for memory device ~ CreateBitmapIndirect 

contexts only, and for only one CreateCompatibleBitmap 

device context at a time.) CreateDIBitmap 

Brush CreateBrushIndirect 
CreateHatchBrush 
CreatePatternBrush 
CreateSolidBrush 

Font CreateFont 
CreateFontIndirect 

Pen CreatePen 
CreatePenIndirect 

Region CombineRgn 
CreateEllipticRgn 
CreateEllipticRgnIndirect 
CreatePolygonRgn 
CreateRectRgn 


CreateRectRgnIndirect 
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Return Value The return value identifies the object being replaced by the object specified by the hObject 
parameter. It is NULL if there is an error. 


If the ADC parameter specifies a metafile, the return value is nonzero if the function is 
successful. Otherwise, it is zero. 


If a region is being selected, the return is the same as for SelectClipRgn. 


Comments When you select a font, pen, or brush by using the SelectObject function, GDI allocates 
space for that object in its data segment. Because data-segment space is limited, you 
should use the DeleteObject function to delete each drawing object that you no longer 
need. 


Before deleting the last of the unneeded drawing objects, an application should select the 
original (default) object back into the device context. 


An application cannot select a bitmap into more than one device context at any time. 


SelectPalette 
Syntax HPALETTE _ SelectPalette(iDC, hPalette, bForceBackground) 


This function selects the logical palette specified by the hPalette parameter as the selected 
palette object of the device context identified by the :DC parameter. The new palette be- 
comes the palette object used by GDI to control colors displayed in the device context and 
replaces the previous palette. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
hPalette HPALETTE Identifies the logical palette to be selected. 


CreatePalette creates a logical palette. 


bForceBackground BOOL Specifies whether the logical palette is forced to 
be a background palette. If bForceBackground is nonzero, 
the selected palette is always a background palette, regard- 
less of whether the window has input focus. If 
bForceBackground is zero, the logical palette is a fore- ee 
ground palette when the window has input focus. x 


Return Value The return value identifies the logical palette being replaced by the palette specified by the 
hPalette parameter. It is NULL if there is an error. 
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Comments An application can select a logical palette into more than one device context. However, 
changes to a logical palette will affect all device contexts for which it is selected. If an 
application selects a palette object into more than one device context, the device contexts 
must all belong to the same physical device (such as a display or printer). 

SendDigitemMessage 

Syntax DWORD  SendDigItemMessage(hD/g, nIDDigltem, wMsg, wParam, lParam) 


Return Value 


Comments 


SendMessage 
Syntax 


This function sends a message to the control specified by the nJ/DD/gItem parameter within 
the dialog box specified by the hD/g parameter. The SendDigItemMessage function does 
not return until the message has been processed. 


Parameter Type/Description 

hDig HWND Identifies the dialog box that contains the control. 

nIDDIgltem int Specifies the integer identifier of the dialog item that is to re- 
ceive the message. 

wMsg WORD Specifies the message value. 

wParam WORD Specifies additional message information. 

IParam DWORD Specifies additional message information. 


The return value specifies the outcome of the function. It is the value returned by the con- 
trol’s window function, or zero if the control identifier is not valid. 


Using SendDlgItemMessage is identical to obtaining a handle to the given control and cal- 
ling the SendMessage function. 


DWORD = SendMessage(hWnd, wMsg, wParam, lParam) 


This function sends a message to a window or windows. The SendMessage function does 
not return until the message has been processed. If the window that receives the message is 
part of the same application, the window function is called immediately as a subroutine. If 
the window is part of another task, Windows switches to the appropriate task and calls the 
appropriate window function, and then passes the message to the window function. The 
message is not placed in the destination application’s queue. 
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SetActiveWindow 


Return Value 


Comments 


Parameter Type/Description 


hWnd HWND Identifies the window that is to receive the message. If the 
hWnd parameter is OxFFFF, the message is sent to all pop-up 
windows in the system. The message is not sent to child windows. 


wMsg WORD Specifies the message to be sent. 
wParam WORD Specifies additional message information. 
[Param DWORD Specifies additional message information. 


The return value specifies the outcome of the function. It is the value returned by the 
window function that received the message; its value depends on the message being sent. 


If a system running Windows is configured for expanded memory (EMS) and an applica- 
tion sends a message (by using the SendMessage function) with related data (that is 
pointed to by the /Param parameter) to a second application, the first application must 
place the data (that /Param points to) in global memory allocated by the GlobalAlloc func- 
tion and the GMEM_LOWER flag. Note that this allocation of memory is only necessary 
if Param contains a pointer. 


SetActiveWindow 


Syntax 


Return Value 


SetBitmapBits 
Syntax 


HWND _ SetActiveWindow(hWnd) 


This function makes a top-level window the active window. 


Parameter Type/Description 


hWnd ‘“HWND Identifies the top-level window to be activated. 


The return value identifies the window that was previously active. The SetActiveWindow 
function should be used with care since it allows an application to arbitrarily take over the 
active window and input focus. Normally, Windows takes care of all activation. 


LONG  SetBitmapBits(/Bitmap, dwCount, IpBits) 


This function sets the bits of a bitmap to the bit values given by the /pBits parameter. 
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Parameter Type/Description 
hBitmap HBITMAP Identifies the bitmap to be set. 
dwCount DWORD Specifies the number of bytes pointed to by /pBits. 
IpBits LPSTR Points to the bitmap bits that are stored as a long pointer 


Return Value 


to a byte array. 


The return value specifies the number of bytes used in setting the bitmap bits. It is zero if 
the function fails. 


SetBitmapDimension 


Syntax 


Return Value 


SetBkColor 
Syntax 


DWORD _ SetBitmapDimension(hBitmap, X, Y) 


This function assigns a width and height to a bitmap in 0.1-millimeter units. These values 
are not used internally by GDI; the GetBitmapDimension function can be used to retrieve 
them. 


Parameter Type/Description 

hBitmap HANDLE Identifies the bitmap. 

X int Specifies the width of the bitmap (in 0.1-millimeter units). 
Y int Specifies the height of the bitmap (in 0.1-millimeter units). 


The return value specifies the previous bitmap dimensions. Height is in the high-order 
word, and width is in the low-order word. 


DWORD SetBkColor(iDC, crColor) 


This function sets the current background color to the color specified by the crColor para- 
meter, or to the nearest physical color if the device cannot represent an RGB color value 
specified by crColor. 


If the background mode is OPAQUE, GDI uses the background color to fill the gaps be- 
tween styled lines, gaps between hatched lines in brushes, and character cells. GDI also 
uses the background color when converting bitmaps from color to monochrome and vice 
versa. 
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The background mode is set by the SetBkMode function. See the BitBIt and StretchBlt 
functions, in this chapter, for color-bitmap conversions. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
crColor COLORREF Specifies the new background color. 
Return Value The return value specifies the previous background color as an RGB color value. If an 


error occurs, the return value is Ox80000000. | 


SetBkMode 
Syntax int SetBkMode(hDC, nBkMode) 


This function sets the background mode used with text and line styles. The background 
mode defines whether or not GDI should remove existing background colors on the device 
surface before drawing text, hatched brushes, or any pen style that is not a solid line. 


Parameter Type/Description 
hDC HDC Identifies the device context. 


nBkMode int Specifies the background mode. It can be either one of the 
following modes: 


Value Meaning 


OPAQUE Background is filled with the current 
background color before the text, 
hatched brush, or pen is drawn. 


TRANSPARENT Background remains untouched. 


Return Value The return value specifies the previous background mode. It can be either OPAQUE or 
TRANSPARENT. 


SetBrushOrg 
Syntax DWORD _ SetBrushOrg(hDC, X, Y) 


This function sets the origin of the brush currently selected into the given device context. 


SetCapture 4-366 
Parameter Type/Description | 
~ hDC HDC Identifies the device context. 
X int Specifies the x-coordinate (in device units) of the new origin. 
This value must be in the range 0~7. 
Y int Specifies the y-coordinate (in device units) of the new origin. 


Return Value 


Comments 


SetCapture 
Syntax 


Return Value 


This value must be in the range 0-7. 


The return value specifies the origin of the brush. The previous x-coordinate is in the low- 
order word, and the previous y-coordinate is in the high-order word. 
The original brush origin is at the coordinate (0,0). 


The SetBrushOrg function should not be used with stock objects. 


HWND _ SetCapture(iWnd) 


This function causes all subsequent mouse input to be sent to the window specified by the 
hWnd parameter, regardless of the position of the cursor. 


Parameter Type/Description 


hWnd HWND Identifies the window that is to receive the mouse input. 


The return value identifies the window that previously received all mouse input. It is 
NULL if there is no such window. 


Comments When the window no longer requires all mouse input, the application should call the 
ReleaseCapture function so that other windows can receive mouse input. 

SetCaretBlinkTime 

Syntax void SetCaretBlinkTime(wM Seconds) 


This function sets the caret blink rate (elapsed time between caret flashes) to the number 
of milliseconds specified by the wMSeconds parameter. The caret flashes on or off each 
wMSeconds milliseconds. This means one complete flash (on-off-on) takes 2 x wMSec- 
onds milliseconds. 
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SetCaretPos 


Return Value 


Comments 


SetCaretPos 
Syntax 


Return Value 


Comments 


SetClassLong 
Syntax 


Parameter Type/Description 


wMSeconds WORD _ Specifies the new blink rate (in milliseconds). 


None. 


The caret is a shared resource. A window should set the caret blink rate only if it owns the 
caret. It should restore the previous rate before it loses the input focus or becomes inactive. 


void SetCaretPos(x, Y) 


This function moves the caret to the position given by logical coordinates specified by the 
X and Y parameters. Logical coordinates are relative to the client area of the window that 
owns them and are affected by the window’s mapping mode, so the exact position in pixels 
depends on this mapping mode. 


The SetCaretPos function moves the caret only if it is owned by a window in the current 
task. SetCaretPos moves the caret whether or not the caret is hidden. 


Parameter Type/Description 

X int Specifies the new x-coordinate (in logical coordinates) of the 
caret. 

Y int Specifies the new y-coordinate (in logical coordinates) of the 
caret. : 

None. 


The caret is a shared resource. A window should not move the caret if it does not own the 
caret. 


LONG __ SetClassLong(iWnd, nIndex, dwNewLong) 


This function replaces the long value specified by the n/ndex parameter in the WND- 
CLASS data structure of the window specified by the hWnd parameter. 


SetClassWord : 4-368 


Return Value 


Comments 


» SetClassWord 
Syntax 


Parameter Type/Description 
hWnd HWND Identifies the window. 
nIndex int Specifies the byte offset of the word to be changed. It can 


also be one of the following values: ° 


Value ; Meaning 

GCL_MENUNAME Sets a new long pointer to the 
: menu name. 

GCL_WNDPROC Sets a new long pointer to the 


_ Window function. 


dwNewLong DWORD Specifies the replacement value. 


The return value specifies the previous value of the specified long integer. 


If the SetClassLong function and GCL_WNDPROC index are used to set a window func- 
tion, the given function must have the window-function form and be exported in the mod- 
ule-definition file. See the RegisterClass function earlier in this chapter for details. 


Calling SetClassLong with the GCL_WNDPROC index creates a subclass of the window 
class that affects all windows subsequently created with the class. See Chapter 1, “Window 
Manager Interface Functions,” for more information on window subclassing. An applica- 
tion should not attempt to create a window subclass for standard Windows controls such as 
combo boxes and buttons. 


To access any extra two-byte values allocated when the window-class structure was 
created, use a positive byte offset as the index specified by the n/ndex parameter, starting 
at zero for the first two-byte value in the extra space, 2 for the next two-byte value and so 
on. 


WORD ~ SetClassWord(hWnad, nindex, wNewWorda) 


This function replaces the word specified by the n/ndex parameter in the WNDCLASS 
structure of the window specified by the hWnd parameter. 
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Parameter Type/Description 
hWnd HWND Identifies the window. 
nIndex int Specifies the byte offset of the word to be changed. It can also 


be one of the following values: 


Value Meaning 
GCW_CBCLSEXTRA Sets two new bytes of addi- 
tional window-class data. 
GCW_CBWNDEXTRA Sets two new bytes of addi- 
tional window-class data. 
GCW_HBRBACKGROUND Sets a new handle to a back- 
ground brush. 
GCW_HCURSOR Sets a new handle to a cursor. 
GCW_HICON Sets a new handle to an icon. 
GCW_STYLE Sets a new style bit for the 
window class. 
wNewWord WORD _Specifies the replacement value. 
Return Value The return value specifies the previous value of the specified word. 
Comments The SetClassWord function should be used with care. For example, it is possible to 


change the background color for a class by using SetClassWord, but this change does not 
cause all windows belonging to the class to be repainted immediately. 


To access any extra four-byte values allocated when the window-class structure was 
created, use a positive byte offset as the index specified by the nJndex parameter, starting 
at zero for the first four-byte value in the extra space, 4 for the next four-byte value and so 


on. 
SetClipboardData 
Syntax HANDLE = SetClipboardData(wFormat, hMem) 


This function sets a data handle to the clipboard for the data specified by the hMem para- 
meter. The data are assumed to have the format specified by the wFormat parameter. After 
setting a clipboard data handle, the SetClipboardData function frees the block of memory 
identified by hMem. 
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Return Value 


Comments 


Parameter Type/Description 


wFormat WORD _ Specifies a data format. It can be any one of the prede- 
fined formats given in Table 4.13, “Predefined Data Formats.” 


In addition to the predefined formats, any format value registered 
through the RegisterClipboardFormat function can be used as the 
wFormat parameter. 


hMem HANDLE Identifies the global memory block that contains the 
data in the specified format. The hMem parameter can be NULL. 
When Mem is NULL the application does not have to format the 
data and provide a handle to it until requested to do so through a 
WM_RENDERFORMAT message. 


The return value identifies the data and is assigned by the clipboard. 


Once the hMem parameter has been passed to SetClipboardData, the block of data be- 


comes the property of the clipboard. The application may read the data, but should not free 
the block or leave it locked. 


Table 4.13 shows the various predefined data-format values for the wFormat parameter: 


Table 4.13. Predefined Data Formats 


Value Meaning 

CF_BITMAP A handle to a bitmap (HBITMAP). 

CF_DIB A memory block containing a BITMAPINFO data structure 
followed by the bitmap bits. 

CF_DIF Software Arts’ Data Interchange Format. 

CF_DSPBITMAP Bitmap display format associated with private format. The 


hMem parameter must be a handle to data that can be displayed 
in bitmap format in lieu of the privately formatted data. 

CF_DSPMETAFILEPICT Metafile-picture display format associated with private format. 
The hMem parameter must be a handle to data that can be dis- 
played in metafile-picture format in lieu of the privately 
formatted data. 

CF_DSPTEXT Text display format associated with private format. The hMem 
parameter must be a handle to data that can be displayed in text 
format in lieu of the privately formatted data. 


CF_METAFILEPICT Metafile picture format as defined by the METAFILEPICT 
data structure. 


4371 SetClipboardData 


Table 4.13 Predefined Data Formats (continued) 


Value Meaning 


CF_OEMTEXT Text format contining characters in the OEM character set. 
Each line ends with a carriage return/linefeed (CR-LF) combi- 
nation. A null character signals the end of the data. 


CF_OWNERDISPLAY Owner display format. The clipboard owner must display and 
update the clipboard application window, and will receive 
WM_ASKCBFORMATNAME, WM_HSCROLLCLIP- 
BOARD, WM_PAINTCLIPBOARD, WM_SIZE- 
CLIPBOARD, and WM_VSCROLLCLIPBOARD messages. 
The hMem parameter must be NULL. 


CF_PALETTE Handle to a color palette. Whenever an application places data 
in the clipboard that depends on or assumes a color palette, it 
should also place the palette in the clipboard as well. 


If the clipboard contains data in the CF_PALETTE (logical 
color palette) format, the application should assume that any 
other data in the clipboard is realized against that logical 
palette. 


The clipboard-viewer application (CLIPBRD.EXE) always 
uses as its current palette any object in CF_PALETTE format 
that is in the clipboard when it displays the other formats in the 


. clipboard. 
CF_PRIVATEFIRST to Range of integer values used for private formats. Data handles 
CF_PRIVATELAST associated with formats in this range will not be freed automati- 


cally; any data handles must be freed by the application before 
the application terminates or when a WM_DESTROY- 
CLIPBOARD message is received. 


CF_SYLK Microsoft Symbolic Link (SYLK) format. 

CF_TEXT Text format. Each line ends with a carriage return/linefeed 
(CR-LF) combination. A null character signals the end of the 
data. 

CF_TIFF Tag Image File Format. 


Windows supports two formats for text, CF_TEXT and CF_OEMTEXT. CF_TEXT is the 
default Windows text clipboard format, while Windows uses the CF_OEMTEXT format 

for text in non-Windows applications. If you call GetClipboardData to retrieve data in 
one text format and the other text format is the only available text format, Windows auto- qw 
matically converts the text to the requested format before supplying it to your application. 


An application registers other standard formats, such as Rich Text Format (RTF), by name 
using the RegisterClipboardFormat function rather than by a symbolic constant. For 
information on these external formats, see the README.TXT file. 
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SetClipboardViewer 
Syntax HWND _ SetClipboard Viewer(hWnd) 


This function adds the window specified by the hWnd parameter to the chain of windows 
that are notified (via the WM_DRAWCLIPBOARD message) whenever the contents of 
the clipboard are changed. . 

Parameter Type/Description 


hWnd HWND Identifies the window to receive clipboard-viewer chain 
messages. 


Return Value The return value identifies the next window in the clipboard-viewer chain. This handle 
should be saved in static memory and used in responding to clipboard-viewer chain mes- 
sages. 


Comments Windows that are part of the clipboard-viewer chain must respond to WM_CHANGECB- 
CHAIN, WM_DRAWCLIPBOARD, and WM_DESTROY messages. 


If an application wishes to remove itself from the clipboard-viewer chain, it must call the 
ChangeClipboardChain function. 


SetCommBreak 
Syntax int SetCommBreak(nCid) 


This function suspends character transmission and places the transmission line in a break 
state until the ClearCommBreak function is called. 


Parameter Type/Description 


nCid int Specifies the communication device to be suspended. The 
OpenComm function returns this value. 


Return Value =—- The return value specifies the result of the function. It is zero if the function is successful. 
It is negative if nCid does not specify a valid device. 
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SetCommEventMask 
Syntax WORD FAR * SetCommEventMask(nCid, nEvtMask) 


Return Value 


Comments 


This function enables and retrieves the event mask of the communication device specified 
by the nCid parameter. The bits of the nEvtMask parameter define which events are to be 
enabled. The return value points to the current state of the event mask. 


Parameter 


nCid 


nEvtMask 


Type/Description 


int Specifies the communication device to be enabled. The Open- 
Comm function returns this value. 


int Specifies which events are to be enabled. It can be any combi- 
nation of the values shown in Table 4.14, “Event Values.” 


The return value points to an integer event mask. Each bit in the event mask specifies 
whether or not a given event has occurred. A bit is 1 if the event has occurred. 


Table 4.14 lists the event values for the nEvtMask parameter: 


Table 4.14 


Value 


EV_BREAK 
EV_CTS 
EV_DSR 
EV_ERR 


EV_PERR 


EV_RING 
EV_RLSD 


EV_RXCHAR 


EV_RXFLAG 


EV_TXEMPTY 


Event Values 


Meaning 


Sets when a break is detected on input. 
Sets when the clear-to-send (CTS) signal changes state. 
Sets when the data-set-ready (DSR) signal changes state. 


Sets when a line-status error occurs. Line-status errors are 
CE_FRAME, CE_OVERRUN, and CE_RXPARITY. 


Sets when a printer error is detected on a parallel device. Errors 
are CE_DNS, CE_IOE, CE_LOOP, and CE_PTO. 


Sets when a ring indicator is detected. 


Sets when the receive-line-signal-detect (RLSD) signal 
changes state. 


Sets when any character is received and placed in the receive 
queue. 


Sets when the event character is received and placed in the re- 


ceive queue. The event character is specified in the device’s pe 


control block. 


Sets when the last character in the transmit queue is sent. 
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SetCommsState 
Syntax int SetCommState(/pDCB) 


This function sets a communication device to the state specified by the device control 
block pointed to by the /pDCB parameter. The device to be set must be identified by the Id 
field of the control block. 


This function reinitializes all hardware and controls as defined by /pDCB, but does not 
empty transmit or receive queues. 
Parameter Type/Description 


lpDCB DCB FAR * Points to a DCB data structure that contains the 
desired communications setting for the device. 


Return Value The return value specifies the outcome of the function. It is zero if the function is success- 
ful. It is negative if an error occurs. 


SetCursor 
Syntax HCURSOR _ SetCursor(hCursor) 


This function sets the cursor shape to the shape specified by the hCursor parameter. The 
cursor is set only if the new shape is different from the current shape. Otherwise, the func- 
tion returns immediately. The SetCursor function is quite fast if the cursor identified by 
the hCursor parameter is the same as the current cursor. 


If hCursor is NULL, the cursor is removed from the screen. 


Parameter Type/Description 


hCursor HCURSOR Identifies the cursor resource. The resource must have 
been loaded previously by using the LoadCursor function. 


Return Value The return value identifies the cursor resource that defines the previous cursor shape. It is 
NULL if there is no previous shape. 


Comments The cursor is a shared resource. A window that uses the cursor should set the shape only 
when the cursor is in its client area or when it is capturing all mouse input. In systems 
without a mouse, the window should restore the previous cursor shape before the cursor 
leaves the client area or before the window relinquishes control to another window. 
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Any application that needs to change the shape of the cursor while it is in a window must 
make sure the class cursor for the given window’s class is set to NULL. If the class cursor 
is not NULL, Windows restores the previous shape each time the mouse is moved. 


The cursor is not shown on the screen if the cursor display count is less than zero. This re- 
sults from the HideCursor function being called more times than the ShowCursor func- 
tion. 


SetCursorPos 
Syntax void SetCursorPos(X, Y) 


This function moves the cursor to the screen coordinates given by the X and Y parameters. 
If the new coordinates are not within the screen rectangle set by the most recent ClipCur- 
sor function, Windows automatically adjusts the coordinates so that the cursor stays within 
the rectangle. 


Parameter Type/Description 


xX int Specifies the new x-coordinate (in screen coordinates) of the 
cursor. 


4 int Specifies the new y-coordinate (in screen coordinates) of the 
cursor. 


Return Value None. 


Comments The cursor is a shared resource. A window should move the cursor only when the cursor is 
in its client area. 


SetDIBits 


Syntax int SetDIBits(hDC, hBitmap, nStartScan, nNumScans, IpBits, lpBitsInfo, wUsage) 


This function sets the bits of a bitmap to the values given in a device-independent bitmap 


(DIB) specification. 
Parameter Type/Description 
hDC HDC _ Identifies the device context. 


hBitmap HBITMAP Identifies the bitmap. 
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Parameter Type/Description 

nStartScan WORD _Specifies the scan number of the first scan line in the 
[pBits buffer. . 

nNumScans WORD Specifies the number of scan lines in the /pBits buffer 


and the number of lines to set in the bitmap identified by the 
hBitmap parameter. 


[pBits LPSTR Points to the device-independent bitmap bits that are 
stored as an array of bytes. The format of the bitmap values de- 
pends on the biBitCount field of the BITMAPINFO structure 
identified by /pBitsInfo. See the description of the BITMAPINFO 
data structure in Chapter 7, “Data Types and Structures,” in 
Reference, Volume 2, for more information. 


[pBitsInfo LPBITMAPINFO Points to a BITMAPINFO data structure 
that contains information about the device-independent bitmap. 
wUsage WORD Specifies whether the bmiColors[ ] fields of the 


IpBitsInfo parameter contain explicit RGB values or indexes into 
the currently realized logical palette. The wUsage parameter must 
be one of the following values: 


Value Meaning 


DIB_PAL_COLORS The color table consists of an array 
of 16-bit indexes into the currently 
realized logical palette. 


DIB_RGB_COLORS The color table contains literal RGB 
values. 
Return Value The return value specifies the number of scan lines successfully copied. It is zero if the 
function fails. 
Comments The bitmap identified by the hBitmap parameter must not be selected into a device context 


when the application calls this function. 


The origin for device-independent bitmaps is the bottom-left corner of the bitmap, not the 
4 . top-left corner, which is the origin when the mapping mode is MM_TEXT. 


This function also accepts a bitmap specification formatted for Microsoft OS/2 Presenta- 
tion Manager versions 1.1 and 1.2 if the /pBitsInfo parameter points to a BITMAPCORE- 
INFO data structure. 
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SetDIBitsToDevice 


SetDIBitsToDevice 


WORD _ SetDIBitsToDevice(hDC, DestX, DestY, nWidth, nHeight, SrcX, SrcY, 
nStartScan, nNumScans, |pBits, lpBitsInfo, wUsage) 


Syntax 


This function sets bits from a device-independent bitmap (DIB) directly on a device sur- 
face. The SrcX, SrcY, nWidth, and nHeight parameters define a rectangle within the total 
DIB. SetDIBitsToDevice sets the bits in this rectangle directly on the display surface of 
the output device identified by the hDC parameter, at the location described by the DestX 
and DestY parameters. 


To reduce the amount of memory required to set bits. from a large DIB on a device surface, 
an application can band the output by repeatedly calling SetDIBitsToDevice, placing a 
different portion of the entire DIB into the /pBits buffer each time. The values of the nStart- 
Scan and nNumScans parameters identify the portion of the entire DIB which is contained 


in the /pBits buffer. 


Parameter 


hDC 
DestX 


DestY 


nWidth 
nHeight 
SrcX 
SrcY 


nStartScan 


nNumScans 


IpBits 


[pBitsInfo 


Type/Description 
HDC Identifies the device context. 


WORD _ Specifies the x-coordinate of the origin of the destina- 
tion rectangle. 


WORD _ Specifies the y-coordinate of the origin of the destina- 
tion rectangle. : 


WORD Specifies the x-extent of the rectangle in the DIB. 
WORD Specifies the y-extent of the rectangle in the DIB. 
WORD Specifies the x-coordinate of the source in the DIB. 
WORD Specifies the y-coordinate of the source in the DIB. 


WORD _ Specifies the scan-line number of the DIB which is con- 
tained in the first scan line of the /pBits buffer. 


WORD _ Specifies the number of scan lines of the DIB which are 
contained in the /pBits buffer. 


LPSTR Points to the DIB bits that are stored as an array of 
bytes. 


LPBITMAPINFO Points to a BITMAPINFO data structure 
that contains information about the DIB. 
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Return Value 


Comments 


SetDigitemint 
Syntax 


Parameter | Type/Description 


. wUsage WORD Specifies whether the bmiColors[ ] fields of the /pBit- 


sInfo parameter contain explicit RGB values or indexes into the 
currently realized logical palette. The wUsage parameter must be 
one of the following values: 


Value Meaning 


DIB_PAL_COLORS The color table consists of an array 
of 16-bit indexes into the currently 
realized logical palette. 


DIB_RGB_COLORS The color table contains literal RGB 
values. 


The return value is the number of scan lines set. 


All coordinates are device coordinates (that is, the coordinates of the DIB) except destX 
and destY, which are logical coordinates. 


The origin for device-independent bitmaps is the bottom-left corner of the DIB, not the top- 
left corner, which is the origin when the mapping mode is MM_TEXT. 


This function also accepts a device-independent bitmap specification formatted for 
Microsoft OS/2 Presentation Manager versions 1.1 and 1.2 if the [pBitsInfo parameter 
points to a BITMAPCOREINFO data structure. 


void SetDigItemInt(Dlg, nIDDlgItem, wValue, bSigned) 


This function sets the text of a control in the given dialog box to the string that represents 
the integer value given by the wValue parameter. The SetDlgItemInt function converts 
wValue to a string that consists of decimal digits, and then copies the string to the control. 
If the bSigned parameter is nonzero, wValue is assumed to be signed. If wValue is signed 
and less than zero, the function places a minus sign before the first digit in the string. 


SetDigItemInt sends a WM_SETTEXT message to the given control. 


Parameter Type/Description 
hDig HWND Identifies the dialog box that contains the control. 


nIDDIglItem int Specifies the control to be modified. 
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Parameter Type/Description 

wValue WORD _ Specifies the value to be set. 

bSigned BOOL _ Specifies whether or not the integer value is signed. 
Return Value None. 
SetDigitemText 
Syntax void SetDigItemText(iD/g, nIDDigltem, IpString) 


This function sets the caption or text of a control in the dialog box specified by the hDlg 
parameter. The SetDigItemText function sends a WM_SETTEXT message to the given 


control. 
Parameter Type/Description 
hDlIg HWND Identifies the dialog box that contains the control. 
nIDDIgItem int Specifies the control whose text is to be set. 
IpString LPSTR Points to the null-terminated character string that is to be 
copied to the control. 
Return Value None. 


SetDoubleClickTime 
Syntax void SetDoubleClickTime(wCount) 


This function sets the double-click time for the mouse. A double-click is a series of two 
clicks of the mouse button, the second occurring within a specified time after the first. The 
double-click time is the maximum number of milliseconds that may occur between the 
first and second clicks of a double-click. 


Parameter Type/Description 


wCount WORD _ Specifies the number of milliseconds that can occur be- 
tween double-clicks. 


Return Value None. 
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Comments 


If the wCount parameter is set to zero, Windows will use the default double-click time of 
500 milliseconds. 


The SetDoubleClickTime function alters the double-click time for all windows in the 
system. 


SetEnvironment 


Syntax 


Return Value 


Comments 


SetErrorMode 
Syntax 


int SetEnvironment(/pPortName, lpEnviron, nCount) 


This function copies the contents of the buffer specified by the /pEnviron parameter into - 
the environment associated with the device attached to the system port specified by the 
IpPortName parameter. The SetEnvironment function deletes any existing environment. 
If there is no environment for the given port, SetEnvironment creates one. If the nCount 
parameter is zero, the existing environment is deleted and not replaced. 


Parameter Type/Description 

IpPortName LPSTR Points to a null-terminated character string that specifies 
the name of the desired port. 

IpEnviron LPSTR Points to the buffer that contains the new environment. 


nCount WORD _ Specifies the number of bytes to be copied. 


The return value specifies the actual number of bytes copied to the environment. It is zero 
if there is an error. It is —-1 if the environment is deleted. 


The first field in the buffer pointed to by the /pEnviron parameter must be the same as that 
passed in the JpDeviceName parameter of the CreateDC function. If IpPortName specifies 
a null port (as defined in the WIN.INI file), the device name pointed to by /pEnviron is 
used to locate the desired environment. 


WORD _ SetErrorMode (wMode) 


This function controls whether Windows handles DOS Function 24H errors or allows the 
calling application to handle them. 


Windows intercepts all INT 24H errors. If the application calls SetErrorMode with the 
wMode parameter set to zero and an INT 24H error subsequently occurs, Windows dis- 

plays an error message box. If the application calls SetErrorMode with wMode set to 1 
and an INT 24H occurs, Windows does not display the standard INT 24H error message 
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SetFocus 


Return Value 


SetFocus 
Syntax 


Return Value 


Comments 


box, but rather fails the original INT 21H call back to the application. This allows the appli- 
cation to handle disk errors using INT 21H, AH=59H (Get Extended Error) as appro- 
priate. 


Parameter Type/Description 


wMode WORD Specifies the error mode flag. If bit 0 is set to zero, 
Windows displays an error message box when an INT 24H error oc- 
curs. If bit 0 is set to 1, Windows fails the INT 21H call to the calling 
application and does not display a message box. 


The return value specifies the previous of the error mode flag. 


HWND _ SetFocus(iWnd) 


This function assigns the input focus to the window specified by the hWnd parameter. The 
input focus directs all subsequent keyboard input to the given window. The window, if any, 
that previously had the input focus loses it. If hWnd is NULL, key strokes are ignored. 


The SetFocus function sends a WM_KILLFOCUS message to the window that loses the 

input focus and a WM_SETFOCUS message to the window that receives the input focus. 
It also activates either the window that receives the focus or the parent of the window that 
receives the focus. 


Parameter Type/Description 


hWnd HWND Identifies the window to receive the keyboard input. 


The return value identifies the window that previously had the input focus. It is NULL if 
there is no such window. 


If a window is active but doesn’t have the focus (that is, no window has the focus), any 
key pressed will produce the WM_SYSCHAR, WM_SYSKEYDOWN, or WM_SYS- 
KEYUP message. If the VK_MENU key is also pressed, the /Param parameter of the 
message will have bit 30 set. Otherwise, the messages that are produced do not have this 
bit set. 
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SetHandleCount 


Syntax 


Return Value 


WORD _ SetHandleCount(wNumber) 


This function changes the number of file handles available to a task. By default, the maxi- 
mum number of file handles available to a task is 20. 


Parameter Type/Description 


wNumber WORD Specifies the number of file handles needed by the 
application. The maximum is 255. 


The return value specifies the number of file handles actually available to the application. 
It may be less than the number specified by the wNumber parameter. 


‘SetKeyboardState 


Syntax 


Return Value 


Comments 


void SetKeyboardState(/pKeyState) 


This function copies the 256 bytes pointed to by the JpKeyState parameter into the 
Windows keyboard-state table. 


Parameter Type/Description 


IpKeyState BYTE FAR * _ Points to an array of 256 bytes that contains key- 
board key states. 


None. 


In many cases, an application should call the GetKeyboardState function first to initialize 
the 256-byte array. The application should then change the desired bytes. 


SetKeyboardState sets the LEDs and BIOS flags for the NUMLOCK, CAPSLOCK, and 
SCROLL LOCK keys according to the toggle state of the VK_NUMLOCK, VK_CAPITAL, 
and VK_OEM_SCROLL entries of the array. 


For more information, see the description of GetKeyboardState, earlier in this chapter. 
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SetMapMode 
Syntax — 


Return Value 


Comments 


int SetMapMode(hDC, nMapMode) 


This function sets the mapping mode of the specified device context. The mapping mode 

defines the unit of measure used to transform logical units into device units, and also de- 

fines the orientation of the device’s x- and y-axes. GDI uses the mapping mode to convert 
logical coordinates into the appropriate device coordinates. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
nMapMode int Specifies the new mapping mode. It can be any one of the 


values shown in Table 4.15, “Mapping Modes.” 


The return value specifies the previous mapping mode. 


The MM_TEXT mode allows applications to work in device pie whose size varies 
from device to device. 


The MM_HIENGLISH, MM_HIMETRIC, MM_LOENGLISH, MM_LOMETRIC, and 
MM_TWIPS modes are useful for applications that need to draw in physically meaningful 
units (such as inches or millimeters). 


The MM_ISOTROPIC mode ensures a 1:1 aspect ratio, which is useful when preserving 
the exact shape of an image is important. 


The MM_ANISOTROPIC mode allows the x- and y-coordinates to be adjusted inde- 
pendently. 


Table 4.15 shows the value and meaning of the various mapping modes: 
Table 4.15 Mapping Modes 


Value Meaning 


MM_ANISOTROPIC Logical units are mapped to arbitrary units with arbitrarily scaled 
axes. The SetWindowExt and Set ViewportExt functions must be 
used to specify the desired units, orientation, and scaling. 


MM_HIENGLISH Each logical unit is mapped to 0.001 inch. Positive x is to the right; 
positive y is up. 
MM_HIMETRIC Each logical unit is mapped to 0.01 millimeter. Positive x is to the 


‘ right; positive y is up. 
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Table 4.15 Mapping Modes (continued) 
Value Meaning 


MM_ISOTROPIC Logical units are mapped to arbitrary units with equally scaled axes; 
that is, one unit along the x-axis is equal to one unit along the y- 
axis. The SetWindowExt and Set ViewportExt functions must be 
used to specify the desired units and the orientation of the axes. GDI 
makes adjustments as necessary to ensure that the x and y units re- 
main the same size. 


MM_LOENGLISH Each logical unit is mapped to 0.01 inch. Positive x is to the right; 
positive y is up. 

MM_LOMETRIC Each logical unit is mapped to 0.1 millimeter. Positive x is to the 
right; positive y is up. 

MM_TEXT Each logical unit is mapped to one device pixel. Positive x is to the 
right; positive y is down. 


MM_TWIPS Each logical unit is mapped to one twentieth of a printer’s point 
(1/1440 inch). Positive x is to the right; positive y is up. 


SetMapperFlags 
Syntax DWORD  SetMapperFlags(hDC, dwFlag) 


This function alters the algorithm that the font mapper uses when it maps logical fonts to 
physical fonts. When the first bit of the wFlag parameter is set to 1, the mapper will only 
select fonts whose x-aspect and y-aspect exactly match those of the specified device. If no 
fonts exist with a matching aspect height and width, GDI chooses an aspect height and 
width and selects fonts with aspect heights and widths that match the one chosen by GDI. 


Parameter Type/Description 

hDC HDC Identifies the device context that contains the font-mapper 
flag. 

dwFlag DWORD _ Specifies whether the font mapper attempts to match a 


font’s aspect height and width to the device. When the first bit is set 
to 1, the mapper will only select fonts whose x-aspect and y-aspect 
exactly match those of the specified device. 


Return Value The return value specifies the previous value of the font-mapper flag. 


Comments The remaining bits of the dwFlag parameter must be zero. 
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SetMenu 
Syntax 


Return Value 


Comments 


BOOL SetMenu(hWnd, hMenu) 


This function sets the given window’s menu to the menu specified by the hMenu parame- 
ter. If hMenu is NULL, the window’s current menu is removed. The SetMenu function 
causes the window to be redrawn to reflect the menu change. 


Parameter Type/Description 
hWnd HWND Identifies the window whose menu is to be changed. 
hMenu HMENU Identifies the new menu. 


The return value specifies whether the menu is changed. It is nonzero if the menu is 
changed. Otherwise, it is zero. 


SetMenu will not destroy a previous menu. An application should call the DestroyMenu 
function to accomplish this task. 


SetMenultemBitmaps 


Syntax 


BOOL SetMenultemBitmaps(hMenu, nPosition, wFlags, hBitmapUnchecked, 
hBitmapCheckead) 


This function associates the specified bitmaps with a menu item. Whether the menu item is 
checked or unchecked, Windows displays the appropriate bitmap next to the menu item. 


Parameter Type/Description 
hMenu HMENU Identifies the menu to be changed. 
nPosition — WORD Specifies the menu item to be changed. If 


wF lags is set to MF_BYPOSITION, nPosition specifies the 
position of the menu item; the first item in the menu is at 
position 0. If wFlags is set to MF_BYCOMMAND, then 
nPosition specifies the command ID of the menu item. 


wFlags WORD _ Specifies how the nPosition parameter is inter- 
preted. It may be set to MF_BYCOMMAND (the default) 
or MF_BYPOSITION. 


hBitmapUnchecked HBITMAP Identifies the bitmap to be displayed when 
_ the menu item is not checked. 
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Return Value 


Comments 


Parameter Type/Description 


hBitmapChecked HBITMAP Identifies the bitmap to be displayed when 
the menu item is checked. 


The return value specifies the outcome of the function. It is TRUE if the function is 
successful. Otherwise, it is FALSE. 


If either the hBitmapUnchecked or the hBitmapChecked parameters is NULL, then 
Windows displays nothing next to the menu item for the corresponding attribute. If both 
parameters are NULL, Windows uses the default checkmark when the item is checked and 
removes the checkmark when the item is unchecked. 


When the menu is destroyed, these bitmaps are not destroyed; it is the responsibility of the 
application to destroy them. 


The GetMenuCheckMarkDimensions function retrieves the dimensions of the default 


checkmark used for menu items. The application should use these values to determine the 


appropriate size for the bitmaps supplied with this function. 


SetMessageQueue 


Syntax 


Return Value 


Comments 


BOOL  SetMessageQueue(cMsg) 


This function creates a new message queue. It is particularly useful in applications that re- 
quire a queue that contains more than eight messages (the maximum size of the default 
queue). The cMsg parameter specifies the size of the new queue; the function must be 
called from an application’s WinMain function before any windows are created and before 
any messages are sent. The SetMessageQueue function destroys the old queue, along with 
messages it might contain. 


Parameter Type/Description 


cMsg int Specifies the maximum number of messages that the new 
queue may contain. 


The return value specifies whether a new message queue is created. It is nonzero if the 
function creates a new queue. Otherwise, it is zero. 


If the return value is zero, the application has no queue because the SetMessageQueue 
function deletes the original queue before attempting to create a new one. The application 
must continue calling SetMessageQueue with a smaller queue size until the function re- 
turns a nonzero value. 
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SetMetaFileBits 
Syntax HANDLE = SetMetaFileBits(iMem) 


Return Value 


Comments 


This function creates a memory metafile from the data in the global memory block 
specified by the hMem parameter. 


Parameter Type/Description 


hMem HANDLE Identifies the global memory block that contains the 
metafile data. It is assumed that the data were previously created by 
using the GetMetaFileBits function. 


The return value identifies a memory metafile if the function is successful. Otherwise, the 
return value is NULL. 


After the SetMetaFileBits function returns, the metafile handle returned by the function 
should be used instead of the handle identified by the }Mem parameter to refer to the meta- 
file. 


SetPaletteEntries 


Syntax 


Return Value 


WORD _ SetPaletteEntries(Palette, wStartIndex, wNumEntries, lpPaletteEntries) 


This function sets RGB color values and flags in a range of entries in a logical palette. 


Parameter _ Type/Description , 

hPalette HPALETTE Identifies the logical palette. 

wStartIndex WORD Specifies the first entry in the logical palette to be set. 

wNumEntries WORD _ Specifies the number of entries in the logical palette 
to be set. 

IpPaletteEntries LPPALETTEENTRY _ Points to the first member of an array 


of PALETTEENTRY data structures containing the RGB 
values and flags. 


- The return value is the number of entries set in the logical palette. It is zero if the function 


failed. 
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Comments If the logical palette is selected into a device context when the application calls SetPalette- 
Entries, the changes will not take effect until the application calls RealizePalette. 


SetParent 
Syntax HWND _ SetParent(hWndChild, hWndNewParent) 


This function changes the parent window of a child window. If the window identified by 
the hWndChild parameter is visible, Windows performs the appropriate redrawing and re- 
painting. 

Parameter Type/Description 


hWndChild HWND Identifies the child window. 
hWndNewParent HWND Identifies the new parent window. 


Return Value The return value identifies the previous parent window. 


SetPixel | 
Syntax DWORD SetPixel(DC, X, Y, crColor) 


This function sets the pixel at the point specified by the X and Y parameters to the closest 
approximation of the color specified by the crColor parameter. The point must be in the 
clipping region. If the point is not in the clipping region, the function is ignored. 
Parameter Type/Description 

hDC HDC Identifies the device context. 

X int Specifies the logical x-coordinate of the point to be set. 


Y int Specifies the logical y-coordinate of the point to be set. 


crColor COLORREF _ Specifies the color used to paint the point. 


Return Value The return value specifies an RGB color value for the color that the point is actually 
painted. This value can be different than that specified by the crColor parameter if an ap- 
proximation of that color is used. If the function fails (if the point is outside the clipping re- 
gion) the return value is —1. 
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SetPolyFillMode 


Comments 


Not all devices support the SetPixel function. For more information, see the RC_BITBLT 
capability in the GetDeviceCaps function, earlier in this chapter. 


SetPolyFillMode 


Syntax 


Return Value 


Comments 


int SetPolyFillMode(iDC, nPolyFillMode) 


This function sets the polygon-filling mode for the GDI functions that use the polygon al- 
gorithm to compute interior points. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
nPolyFillMode int Specifies the new filling mode. The nPolyFillMode para- 
meter may be either of the following values: 
Value Meaning 
ALTERNATE Selects alternate mode. 
WINDING Selects winding number mode. 


The return value specifies the previous filling mode. It is zero if there is an error. 


In general, the modes differ only in cases where a complex, overlapping polygon must be 
filled (for example, a five-sided polygon that forms a five-pointed star with a pentagon in 
the center). In such cases, ALTERNATE mode fills every other enclosed region within the 
polygon (that is, the points of the star), but WINDING mode fills all regions (that is, the 
points and the pentagon). 


When the filling mode is ALTERNATE, GDI fills the area between odd-numbered and 
even-numbered polygon sides on each scan line. That is, GDI fills the area between the 
first and second side, between the third and fourth side, and so on. 


To fill all regions, WINDING mode causes GDI to compute and draw a border that en- 
closes the polygon but does not overlap. For example, in WINDING mode, the five-sided 
polygon that forms the star is drawn as a ten-sided polygon with no overlapping sides; the 
resulting star is filled. 
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SetProp 
Syntax BOOL  SetProp(AWnd, IpString, hData) 


This function adds a new entry or changes an existing entry in the property list of the 
specified window. The SetProp function adds a new entry to the list if the character string 
specified by the /pString parameter does not already exist in the list. The new entry con- 
tains the string and the handle. Otherwise, the function replaces the string’s current handle 
with the one specified by the hData parameter. 


The hData parameter can contain any 16-bit value useful to the application. 


Parameter Type/Description 


hWnd HWND Identifies the window whose property list is to receive the 
new entry. . 


IpString LPSTR Points to a null-terminated character string or an atom that 
identifies a string. If an atom is given, it must have been previously 
created by using the AddAtom function. The atom, a 16-bit value, 
must be placed in the low-order word of /pString; the high-order 
word must be zero. 


hData HANDLE Identifies a data handle to be copied to the property list. 


Return Value The return value specifies the outcome of the function. It is nonzero if the data handle and 
string are added to the property list. Otherwise, it is zero. 


Comments The application is responsible for removing all entries it has added to the property list 
before destroying the window (that is, before the application processes the WM_DE- 
STROY message). The RemoveProp function must be used to remove entries from a prop- 
erty list. 


SetRect 
Syntax void SetRect(/pRect, X1, Y1, X2, Y2) 


This function creates a new rectangle by filling the RECT data structure pointed to by the 
IpRect parameter with the coordinates given by the X/, Y/, X2, and Y2 parameters. 
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Parameter Type/Description 
IpRect LPRECT Points to the RECT data structure that is to receive the 
new rectangle coordinates. 
X1 int Specifies the x-coordinate of the upper-left corner. 
Yl int Specifies the y-coordinate of the upper-left corner. 
X2 int Specifies the x-coordinate of the lower-right corner. 
Y2 int Specifies the y-coordinate of the lower-right corner. 
Return Value None. 
Comments The width of the rectangle, specified by the absolute value of X2 — X/, must not exceed 


32,767 units. This limit applies to the height of the rectangle as well. 


SetRectEmpty 
Syntax void SetRectEmpty(/pRect) 
This function creates an empty rectangle (all coordinates equal to zero). 
Parameter Type/Description 
IpRect LPRECT _ Points to the RECT data structure that is to receive the 
empty rectangle. 
Return Value None. 
SetRectRgn 
Syntax void SetRectRgn(hRegn, X/, Y1, X2, Y2) 


This function creates a rectangular region. Unlike CreateRectRegion, however, it does 
not call the local memory manager; instead, it uses the space allocated for the region as- 
sociated with the hRgn parameter. The points given by the X/, Y/, X2, and Y2 parameters 
specify the minimum size of the allocated space. 
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Parameter Type/Description 
hRgn HANDLE Identifies the region. 
X1 int Specifies the x-coordinate of the upper-left comer of the rec- 
tangular region. 
Yl int Specifies the y-coordinate of the upper-left comer of the rec- 
tangular region. 
X2 int Specifies the x-coordinate of the lower-right corner of the rec- 
tangular region. 
Y2 int Specifies the y-coordinate of the lower-right corner of the rec- 
tangular region. — ; 
Return Value None. 
Comments Use this function instead of the CreateRectRgn function to avoid calls to the local 


memory manager. 


SetResourceHandler 
Syntax FARPROC  SetResourceHandler(h/nstance, IpType, lpLoadFunc) 


This function sets up a function to load resources. It is used internally by Windows to im- 
plement calculated resources. Applications may find this function useful for handling their 
own resource types, but its use is not required. The /pLoadF unc parameter points to an 
application-supplied callback function. The function pointed to by the JpLoadFunc parame- 
ter receives information about the resource to be locked and can process that information 
as desired. After the function pointed to by /pLoadFunc returns, LockResource attempts 

to lock the resource once more. 
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SetResourceHandler 


Return Value 


Comments 


Callback Function 


Parameter Type/Description 


hInstance HANDLE Identifies the instance of the module whose executable 
file contains the resource. 


IpType LPSTR Points to a short integer that specifies a resource type. 


IpLoadFunc FARPROC Is the procedure-instance address of the application- 
supplied callback function. See the following “Comments” section 
for details. 


The return value points to the application-supplied function. 
The callback function must use the Pascal calling convention and must be declared FAR. 


FARPROC FAR PASCAL LoadFunc(hMem, hInstance, hResInfo) 
HANDLE Mem; 

HANDLE hilnstance; 

HANDLE hResInfo; 


LoadFunc is a placeholder for the application-supplied function name. The actual name 


must be exported by including it in an EXPORTS statement in the application’s module- 
definition file. 


Parameter Description 
hMem Identifies a stored resource. 
hInstance Identifies the instance of the module whose executable file contains 


the resource. 


hResInfo Identifies the resource. It is assumed that the resource was created 
previously by using the FindResource function. 
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Comments 


The hMem parameter is NULL if the resource has not yet been loaded. If an attempt to 
lock a block specified by hMem fails, this means the resource has been discarded and must 
be reloaded. 


The dialog-function address, passed as the /pLoadFunc parameter, must be created by 
using the MakeProcInstance function. 


SetROP2 
Syntax int SetROP2(hDC, nDrawMode) 


This function sets the current drawing mode. GDI uses the drawing mode to combine pens 
and interiors of filled objects with the colors already on the display surface. The mode 
specifies how the color of the pen or interior and the color already on the display surface 
yield a new color. 


Parameter Type/Description 
hDC HDC Identifies the device context. 


nDrawMode int Specifies the new drawing mode. It can be any one of the 
values given in Table 4.16, “Drawing Modes.” 


Return Value The return value specifies the previous drawing mode. It can be any one of the values 
given in Chapter 11, “Binary and Ternary Raster-Operation Codes,” in Reference, Volume 
2 


Comments Drawing modes define how GDI combines source and destination colors when drawing 
with the current pen. The drawing modes are actually binary raster-operation codes, repre- 
senting all possible Boolean functions of two variables, using the binary operations AND, 
OR, and XOR (exclusive OR), and the unary operation NOT. The drawing mode is for 
raster devices only; it is not available on vector devices. For more information, see the 
RC_BITBLT capability in the GetDeviceCaps function, earlier in this chapter. Table 4.16 
shows the value of various drawing modes for the nDrawMode parameter: 


Table 4.16 Drawing Modes 


Value 


R2_BLACK 
R2_WHITE 

R2_NOP 

R2_NOT 
R2_COPYPEN 
R2_NOTCOPYPEN 
R2_MERGEPENNOT 


R2_MASKPENNOT 
R2_MERGENOTPEN 
R2_MASKNOTPEN 


R2_MERGEPEN 
R2_NOTMERGEPEN 
R2_MASKPEN 


R2_NOTMASKPEN 
R2_XORPEN 


R2_NOTXORPEN 


Meaning 


Pixel is always black. 

Pixel is always white. 

Pixel remains unchanged. 

Pixel is the inverse of the display color. 
Pixel is the pen color. 

Pixel is the inverse of the pen color. 


Pixel is a combination of the pen color and the inverse of the 
display color. 


Pixel is a combination of the colors common to both the pen 
and the inverse of the display. 


Pixel is a combination of the display color and the inverse of 
the pen color. 


Pixel is a combination of the colors common to both the dis- 
play and the inverse of the pen. 


Pixel is a combination of the pen color and the display color. 
Pixel is the inverse of the R2_MERGEPEN color. 


Pixel is a combination of the colors common to both the pen 
and the display. 


Pixel is the inverse of the R2_. MASKPEN color. 


Pixel is a combination of the colors in the pen and in the dis- 
play, but not in both. 


Pixel is the inverse of the R2_XORPEN color. 


For more information about the drawing modes, see Chapter 11, “Binary and Ternary 
Raster-Operation Codes,” in Reference, Volume 2. 
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SetScrollPos 
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SetScrollPos 
Syntax 


Return Value 


Comments 


int SetScrollPos(;Wnd, nBar, nPos, bRedraw) 


This function sets the current position of a scroll-bar thumb to that specified by the nPos 
parameter and, if specified, redraws the scroll bar to reflect the new position. 


Parameter 


hWnd 


nBar 


nPos 


bRedraw 


Type/Description 
HWND Identifies the window whose scroll bar is to be set. 


int Specifies the scroll bar to be set. It can be one of the fol- 
lowing values: 


Value Meaning 


SB_CTL Sets the position of a scroll-bar control. 
In this case, the hWnd parameter must be 
the handle of a scroll-bar control. 


SB_HORZ Sets a window’s horizontal scroll-bar 
position. 

SB_VERT Sets a window’s vertical scroll-bar posi- 
tion. 


int Specifies the new position. It must be within the scrolling 
range. 


BOOL _ Specifies whether the scroll bar should be redrawn to 
reflect the new position. If the bRedraw parameter is nonzero, 
the scroll bar is redrawn. If it is zero, it is not redrawn. 


The return value specifies the previous position of the scroll-bar thumb. 


Setting the bRedraw parameter to zero is useful whenever the scroll bar will be redrawn by 
a subsequent call to another function. 
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SetScrollRange 
Syntax void SetScrollRange(hWnd, nBar, nMinPos, nMaxPos, bRedraw) 
This function sets minimum and maximum position values for the given scroll bar. It can 
also be used to hide or show standard scroll bars by setting the nMinPos and nMaxPos par- 
ameters to zero. 
Parameter Type/Description 
hWnd HWND Identifies a window or a scroll-bar control, depending 
on the value of the nBar parameter. 
nBar int Specifies the scroll bar to be set. It can be one of the follow- 
ing values: 
Value Meaning 
SB_CTL Sets the range of a scroll-bar control. In 
this case, the hWnd parameter must be 
the handle of a scroll-bar control. 
SB_HORZ Sets a window’s horizontal scroll-bar 
range. 
SB_VERT Sets a window’s vertical scroll-bar range. 
nMinPos int Specifies the minimum scrolling position. 
nMaxPos int Specifies the maximum scrolling position. 
bRedraw BOOL _ Specifies whether or not the scroll bar should be red- 
rawn to reflect the change. If the bRedraw parameter is nonzero, 
the scroll bar is redrawn. If it is zero, it is not redrawn. 
Return Value None. 
Comments An application should not call this function to hide a scroll bar while processing a scroll- 


bar notification message. 


If SetScrollRange immediately follows the SetScrollPos function, the bRedraw parameter 
in SetScrollPos should be set to zero to prevent the scroll bar from being drawn twice. 


The difference between the values specified by the nMinPos and nMaxPos parameters 
must not be greater than 32,767. 


SetSoundNoise 
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SetSoundNoise 
Syntax int SetSoundNoise(nSource, nDuration) 
This function sets the source and duration of a noise in the noise hardware of the play 
device. 
Parameter Type/Description 
nSource int Specifies the noise source. It can be any one of the following 
values, where N is a value used to derive a target frequency: 
Value Meaning 
S_PERIODS512 Source frequency is N/512 (high 
pitch); hiss is less coarse. 
S_PERIOD1024 Source frequency is N/1024. 
S_PERIOD2048 Source frequency is N/2048 (low 
pitch); hiss is coarser. 
S_PERIODVOICE Source frequency from voice chan- 
nel 3. 
S_WHITES512 Source frequency is N/512 (high 
pitch); hiss is less coarse. 
S_WHITE1024 Source frequency is N/1024. 
S_WHITE2048 Source frequency is N/2048 (low 
pitch); hiss is coarser. 
S_WHITEVOICE Source frequency from voice chan- 
nel 3. 
nDuration int Specifies the duration of the noise (in clock ticks). 
Return Value The return value specifies the result of the function. It is zero if the function is successful. 
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 SetStretchBitMode 


Syntax int SetStretchBltMode(hDC, nStretchMode) 


If the source is invalid, the return value is S SERDSR. 


This function sets the stretching mode for the StretchBlt function. The stretching mode de- 
fines which scan lines and/or columns StretchBlt eliminates when contracting a bitmap. 
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Parameter Type/Description 
hDC HDC Identifies the device context. 
nStretchMode int Specifies the new stretching mode. It can be one of the fol- 


lowing values: 


Value Meaning 


BLACKONWHITE AND in the eliminated lines. This 
mode preserves black pixels at the 
expense of white pixels by using the 
AND operator on the eliminated 
lines and those remaining. 


COLORONCOLOR Deletes the eliminated lines. This 
mode deletes all eliminated lines 
without trying to preserve their 
information. 


WHITEONBLACK OR in the eliminated lines. This 
mode preserves white pixels at the 
expense of black pixels by using the 
OR operator on the lines to be elimi- 
nated and the remaining lines. 


The BLACKONWHITE and WHITEONBLACK modes are typi- 
cally used to preserve foreground pixels in monochrome bitmaps. 
The COLORONCOLOR mode is typically used to preserve color 
in color bitmaps. 


Return Value The return value specifies the previous stretching mode. It can be BLACKONWHITE, 
COLORONCOLOR, or WHITEONBLACK. 


SetSwapAreaSize 
Syntax LONG  SetSwapAreaSize(rsSize) 
This function increases the amount of memory that an application uses for its code 


segments. The maximum amount of memory available is one-half of the space remaining 
after Windows is loaded. 
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Return Value 


Comments 


‘SetSysColors 
Syntax 


Parameter Type/Description 


rsSize WORD _ Specifies the number of 16-byte paragraphs requested by 
the application for use as a code segment. 


The low-order word of the return value specifies the number of paragraphs obtained for 
use as a code segment space (or the current size if rsSize is zero); the high-order word 
specifies the maximum size available. 


If rsSize specifies a size larger than is available, this function sets the size to the available 
amount. 


Once memory has been dedicated for use as code segment space, an application cannot use 
it as a data segment by calling the GlobalAlloc function. 


Calling this function improves an application’s performance by helping prevent thrashing. 
However, it reduces the amount of memory available for data objects and can reduce the 
performance of other applications. Before calling SetSwapAreaSize, an application 
should call GetNumTasks to determine how many other tasks are running. 


void SetSysColors(nChanges, lpSysColor, lpColorValues) 


This function sets the system colors for one or more display elements. Display elements 
are the various parts of a window and the Windows display that appear on the system dis- 
play screen. The SetSysColors function changes the number of elements specified by the 
nChanges parameter, using the color and system-color index contained in the arrays 
pointed to by the /pSysColor and [pColorValues parameters. 


SetSysColors sends a WM_SYSCOLORCHANGE message to all windows to inform 
them of the change in color. It also directs Windows to repaint the affected portions of all 
currently visible windows. 


Parameter Type/Description 
nChanges int Specifies the number of system colors to be changed. 


IpSysColor LPINT Points to an array of integer indexes that specify the ele- 
. ments to be changed. The index values that can be used are listed 
in Table 4.17, “System Color Indexes.” 


IpColorValues DWORD FAR * | Points to an array of unsigned long integers 
that contains the new RGB color values for each element. 
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Return Value 


None. 


SetSysModalWindow 


Comments ‘SetSysColors changes the internal system list only. It does not change the [COLORS] sec- 
tion of the Windows initialization file, WIN.INI. Changes apply to the current Windows 
session only. System colors are a shared resource. An application should not change a 
color if it does not wish to change colors for all windows in all currently running applica- 
tions. System colors for monochrome displays are usually interpreted as various shades of 
gray. Table 4.17 lists the values for the JpSysColor parameter: 

Table 4.17 System Color Indexes 
Value Meaning 
COLOR_ACTIVEBORDER Active window border. 
COLOR_ACTIVECAPTION Active window caption. 
COLOR_APPWORKSPACE Background color of multiple document interface (MDI) 
applications. 
COLOR_BACKGROUND Desktop. 
COLOR_BTNFACE Face shading on push buttons. 
COLOR_BTNSHADOW Edge shading on push buttons. 
COLOR_BTNTEXT Text on push buttons. 
COLOR_CAPTIONTEXT Text in caption, size box, scroll-bar arrow box. 
COLOR_GRAYTEXT Grayed (disabled) text. This color is set to 0 if the cur- 
rent display driver does not support a solid gray color. 

COLOR_HIGHLIGHT Items selected item in a control. 
COLOR_HIGHLIGHTTEXT Text of item selected in a control. 
COLOR_INACTIVEBORDER Inactive window border. 
COLOR_INACTIVECAPTION Inactive window caption. 
COLOR_MENU Menu background. 
COLOR_MENUTEXT Text in menus. 
COLOR_SCROLLBAR Scroll-bar gray area. 
COLOR_WINDOW Window background. 
COLOR_WINDOWFRAME Window frame. 
COLOR_WINDOWTEXT Text in windows. 

SetSysModalWindow | 

Syntax HWND _ SetSysModalWindow(hWnd) 


This function makes the specified window a system-modal window. 
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Parameter Type/Description 

hWnd HWND Identifies the window to be made system modal. 
Return Value The return value identifies the window that was previously the system-modal window. 
Comments If another window is made the active window (for example, the system-modal window 


creates a dialog box that becomes the active window), the active window becomes the sys- 
tem-modal window. When the original window becomes active again, it is system modal. 
To end the system-modal state, destroy the system-modal window. 


SetSystemPaletteUse 
Syntax WORD _ SetSystemPaletteUse(iDC, wUsage) 


This function allows an application to use the full system palette. By default, the system 
palette contains 20 static colors which are not changed when an application realizes its 


i 
& 
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logical palette. 
The device context identified by the hDC parameter must refer to a device that supports’ 
color palettes. 
Parameter Type/Description 
hDC HDC Identifies the device context. 
wUsage WORD _Specifies the new use of the system palette. It can be 
either of these values: 
Value Meaning 
SYSPAL_NOSTATIC System palette contains no static colors 
except black and white. 
SYSPAL_STATIC System palette contains static colors 
which will not change when an applica- 
tion realizes its logical palette. 
Return Value The return value specifies the previous usage of the system palette. It is either SYS- 


PAL_NOSTATIC or SYSPAL_STATIC. 


Comments An application must call this function only when its window has input focus. 
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If an application calls SetSystemPaletteUse with wUsage set to SYSPAL_NOSTATIC, 
Windows continues to set aside two entries in the system palette for pure white and pure 
black, respectively. 
After calling this function with wUsage set to SYSPAL_NOSTATIC, an application must 
follow these steps: : 
1. Call UnrealizeObject to force GDI to remap the logical palette completely when it is 
realized. 
2. Realize the logical palette. 
3. Call GetSysColors to save the current system-color settings. 
4. Call SetSysColors to set the system colors to reasonable values using black and white. 
For example, adjacent or overlapping items (such as window frames and borders) 
should be set to black and white, respectively. 
5. Broadcast the WM_SYSCOLORCHANGE message to allow other windows to be red- 
rawn with the new system colors. 
When the application’s window loses focus or closes, the application must perform the fol- 
lowing steps: 
1. Call SetSystemPaletteUse with the wUsage parameter set to SYSPAL_STATIC. 
2. Call UnrealizeObject to force GDI to remap the logical palette completely when it is 
realized. 
3. Realize the logical palette. 
4. Restore the system colors to their previous values. 
5. Broadcast the WM_SYSCOLORCHANGE message. 
SetTextAlign 
Syntax WORD  SetTextAlign(ADC, wFlags) 


This function sets the text-alignment flags for the given device context. The TextOut and 
ExtTextOut functions use these flags when positioning a string of text on a display or 
device. The flags specify the relationship between a specific point and a rectangle that 
bounds the text. The coordinates of this point are passed as parameters to the TextOut 
function. The rectangle that bounds the text is formed by the adjacent character cells in the 
text string. , 
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Parameter Type/Description 
hDC HDC _ Identifies the device or display selected for text output. 
wFlags WORD Specifies a mask of the values in the following list. Only 


one flag may be chosen from those that affect horizontal and verti- 
cal alignment. In addition, only one of the two flags that alter the 
current position can be chosen: 


Value Meaning 

TA_BASELINE Specifies alignment of the point and 
the baseline of the chosen font. 

TA_BOTTOM Specifies alignment of the point and 
the bottom of the bounding 
rectangle. 

TA_CENTER Specifies alignment of the point and 


the horizontal center of the bound- 
ing rectangle. 


TA_LEFT Specifies alignment of the point and 
the left side of the bounding 
rectangle. 

TA_NOUPDATECP Specifies that the current position is 


not updated after each TextOut or 
ExtTextOut function call. 


TA_RIGHT Specifies alignment of the point and 
the right side of the bounding 
rectangle. 

TA_TOP Specifies alignment of the point and 


the top of the bounding rectangle. 


TA_UPDATECP Specifies that the current position is 
updated after each TextOut or Ext- 
TextOut function call. 


The defaults are TA_LEFT, TA_TOP, and TA_.NOUPDATECP. 


“Return Value The return value specifies the previous text alignment setting; the low-order word contains 
the horizontal alignment, and the high-order word contains the vertical alignment. 
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SetTextCharacterExtra 
Syntax int SetTextCharacterExtra(iDC, nCharExtra) 


This function sets the amount of intercharacter spacing. GDI adds this spacing to each 
character, including break characters, when it writes a line of text to the device context. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
nCharExtra int Specifies the amount of extra space (in logical units) to be 


added to each character. If the current mapping mode is not 
MM_TEXT, the nCharExtra parameter is transformed and rounded 
to the nearest pixel. 


Return Value The return value specifies the amount of the previous intercharacter spacing. 
SetTextColor 
Syntax DWORD _ SetTextColor(iDC, crColor) 


This function sets the text color to the color specified by the crColor parameter, or to the 
nearest physical color if the device cannot represent the color specified by crColor. GDI 
uses the text color to draw the face of each character written by the TextOut and ExtText- 
Out functions. GDI also uses the text color when converting bitmaps from color to mono- 
chrome and vice versa. 


The background color for a character is specified by the SetBkColor and SetBkMode 
functions. For color-bitmap conversions, see the BitBIt and StretchBlt functions, earlier in 
this chapter. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
crColor COLORREF _ Specifies the color of the text. 


Return Value The return value specifies an RGB color value for the previous text color. 
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SetTextJustification 


Syntax 


Return Value 


int SetTextJustification(hDC, nBreakExtra, nBreakCount) 


This function prepares GDI to justify a line of text using the justification parameters 
specified by the nBreakExtra and nBreakCount parameters. To justify text, GDI distributes 
extra pixels among break characters in a text line written by.the TextOut function. The 
break character, used to delimit words, is usually the space character (ASCII 32), but may 
be defined by a font as some other character. The GetTextMetrics function can be used to 
retrieve a font’s break character. 


The SetTextJustification function prepares the justification by defining the amount of 
space to be added. The nBreakExtra parameter specifies the total amount of space (in logi- 
cal units) to be added to the line. The nBreakCount parameter specifies how many break 
characters are in the line. The subsequent TextOut function distributes the extra space 
evenly between each break character in the line. 


GetTextExtent is always used with the SetTextJustification function. The GetText- 
Extent function computes the width of a given line before justification. This width must 
be known before an appropriate nBreakExtra value can be computed. 


SetText Justification can be used to justify a line that contains multiple runs in different 
fonts. In this case, the line must be created piecemeal by justifying and writing each run 
separately. 


Because rounding errors can occur during justification, GDI keeps a running error term 
that defines the current error. When justifying a line that contains multiple runs, GetText- 
Extent automatically uses this error term when it computes the extent of the next run, al- 
lowing TextOut to blend the error into the new run. After each line has been justified, this 
error term must be cleared to prevent it from being incorporated into the next line. The 
term can be cleared by calling SetText Justification with nBreakExtra set to zero. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
nBreakExtra int Specifies the total extra space (in logical units) to be added to 


the line of text. If the current mapping mode is not MM_TEXT, the 
value identified by the nBreakExtra parameter is transformed and 
rounded to the nearest pixel. 


nBreakCount int Specifies the number of break characters in the line. 


The return value specifies the outcome of the function. It is 1 if the function is successful. 
Otherwise, it is zero. 
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SetTimer 


SetTimer 
Syntax 


Return Value 


Comments 


Callback Function 


WORD _ SetTimer(hWnd, nIDEvent, wElapse, lpTimerFunc) 


This function creates a system timer event. When a timer event occurs, Windows passes a 
WML_TIMER message to the application-supplied function specified by the /pTimerFunc 
parameter. The function can then process the event. A NULL value for /pTimerFunc causes 
WM_TIMER messages to be placed in the application queue. 


Parameter Type/Description 

hWnd HWND Identifies the window to be associated with the timer. If 
hWnd is NULL, no window is associated with the timer. 

nlDEvent int Specifies a nonzero timer-event identifier if the hWnd parame- 
ter is not NULL. 

wElapse WORD _Specifies the elapsed time (in milliseconds) between timer 
events. 


IpTimerFunc FARPROC Is the procedure-instance address of the function to be 
notified when the timer event takes place. If IpTimerFunc is NULL, 
the WM_TIMER message is placed in the application queue, and the 
hwnd member of the MSG structure contains the hWnd parameter 
given in the SetTimer function call. See the following “Comments” 
section for details. 


The return value specifies the integer identifier for the new timer event. If the hWnd para- 
meter is NULL, an application passes this value to the KillTimer function to kill the timer 
event. The return value is zero if the timer was not created. 


Timers are a limited global resource; therefore, it is important that an application check the 
value returned by the SetTimer function to verify that a timer is actually available. 


To install a timer function, SetTimer must receive a procedure-instance address of the 
function, and the function must be exported in the application’s module-definition file. A 
procedure-instance address can be created using the MakeProclInstance function. 


The callback function must use the Pascal calling convention and must be declared FAR. 


WORD FAR PASCAL TimerFunc(hWnd, wMsg, nIDEvent, dwTime) 
HWND hWnd; 

WORD wMszg; 

int nIDEvent; 

DWORD dwTime; 
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SetViewportExt 


Syntax 


TimerF unc is a placeholder for the application-supplied function name. The actual name 


must be exported by including it in an EXPORTS statement in the application’s module- 
definition file. 


Parameter Description 

hWnd Identifies the window associated with the timer event. 
wMsg Specifies the WM_TIMER message. 

nlDEvent Specifies the timer’s ID. 

dwTime Specifies the current system time. 


DWORD _ SetViewportExt(iDC, x, Y) 


This function sets the x- and y-extents of the viewport of the specified device context. The 
viewport, along with the device-context window, defines how GDI maps points in the logi- 
cal coordinate system to points in the coordinate system of the actual device. In other 
words, they define how GDI converts logical coordinates into device coordinates. 


The x- and y-extents of the viewport define how much GDI must stretch or compress units 
in the logical coordinate system to fit units in the device coordinate system. For example, 
if the x-extent of the window is 2 and the x-extent of the viewport is 4, GDI maps two logi- 
cal units (measured from the x-axis) into four device units. Similarly, if the y-extent of the 
window is 2 and the y-extent of the viewport is —1, GDI maps two logical units (measured 
from the y-axis) into one device unit. 


The extents also define the relative orientation of the x- and y-axes in both coordinate sys- 
tems. If the signs of matching window and viewport extents are the same, the axes have 
the same orientation. If the signs are different, the orientation is reversed. For example, if 
the y-extent of the window is 2 and the y-extent of the viewport is —1, GDI maps the posi- 
tive y-axis in the logical coordinate system to the negative y-axis in the device coordinate 
system. If the x-extents are 2 and 4, GDI maps the positive x-axis in the logical coordinate 
system to the positive x-axis in the device-coordinate system. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
Xx int Specifies the x-extent of the viewport (in device units). 


Y int Specifies the y-extent of the viewport (in device units). 
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Return Value The return value specifies the previous extents of the viewport. The previous y-extent is in 
the high-order word; the previous x-extent is in the low-order word. When an error occurs, 
the return value is zero. 


Comments: When the following mapping modes are set, calls to the SetWindowExt and Set View- 
portExt functions are ignored: 


= MM_HIENGLISH 
= MM_HIMETRIC 

= MM_LOENGLISH 
4" MM_LOMETRIC 
=m MM_TEXT 

= MM_TWIPS 


When MM_ISOTROPIC mode is set, an application must call the SetWindowExt func- 
tion before it calls SetViewportExt. 


SetViewportOrg 
Syntax DWORD _SetViewportOrg(hDC, X, Y) 


This function sets the viewport origin of the specified device context. The viewport, along 
with the device-context window, defines how GDI maps points in the logical coordinate 
system to points in the coordinate system of the actual device. In other words, they define 
how GDI converts logical coordinates into device coordinates. 


The viewport origin marks the point in the device coordinate system to which GDI maps . 
the window origin, a point in the logical coordinate system specified by the SetWindow- 
Org function. GDI maps all other points by following the same process required to map 
the window origin to the viewport origin. For example, all points in a circle around the 
point at the window origin will be in a circle around the point at the viewport origin. Simi- 
larly, all points in a line that passes through the window origin will be in a line that passes 
through the viewport origin. 


Parameter Type/Description 
~hDC HDC Identifies the device context. 
x int Specifies the x-coordinate (in device units) of the origin of the 


viewport. The value must be within the range of the device coordi- 
nate system. 
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Parameter Type/Description 


Y . int Specifies the y-coordinate (in device units) of the origin of the 
viewport. The value must be within the range of the device coordi- 
nate system. 


Return Value The return value specifies the previous origin of the viewport (in device coordinates). The 
y-coordinate is in the high-order word; the x-coordinate is in the low-order word. 


SetVoiceAccent 


Syntax int SetVoiceAccent(nVoice, nTempo, nVolume, nMode, nPitch) 


This function places an accent (tempo, volume, mode, and pitch) in the voice queue 
specified by the nVoice parameter. The new accent replaces the previous accent and re- 
mains in effect until another accent is queued. An accent is not counted as a note. 


An error occurs if there is insufficient room in the queue; the Set VoiceAccent function al- 
ways leaves space for a single sync mark in the queue. If nVoice is out of range, the 
Set VoiceAccent function is ignored. 


Parameter Type/Description 
nVoice int Specifies a voice queue. The first voice queue is numbered 1. 
nTempo int Specifies the number of quarter notes played per minute. It 


can be any value from 32 to 255. The default is 120. 


nVolume int Specifies the volume level. It can be any value from 0 
(lowest volume) to 255 (highest). 


nMode int Specifies how the notes are to be played. It can be any one of 
the following values: 


Value Meaning 

S_LEGATO Note is held for the full duration and blended 
with the beginning of the next note. 

S_NORMAL Note is held for the full duration, coming to a 


full stop before the next note starts. 


S_STACCATO Note is held for only part of the duration, 
creating a pronounced stop between it and the 
next note. 
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Parameter Type/Description 


nPitch int Specifies the pitch of the notes to be played. It can be any 
value from 0 to 83. The pitch value is added to the note value, 
using modulo 84 arithmetic. 


Return Value The return value specifies the result of the function. It is zero if the function is successful. 
; If an error occurs, the return value is one of the following values: 


Value Meaning 
S_SERDMD Invalid mode 
S_SERDTP Invalid tempo 
S_SERDVL Invalid volume 
S_SERQFUL Queue full 


SetVoiceEnvelope 


Syntax int SetVoiceEnvelope(nVoice, nShape, nRepeat) 


This function queues the envelope (wave shape and repeat count) in the voice queue 
specified by the nVoice parameter. The new envelope replaces the previous one and re- 


mains in effect until the next Set VoiceEnvelope function call. An envelope is not counted 
as a note. 


An error occurs if there is insufficient room in the queue; the Set VoiceEnvelope function 
always leaves space for a single sync mark in the queue. If nVoice is out of range, 
Set VoiceEnvelope is ignored. 


Parameter Type/Description 

nVoice int Specifies the voice queue to receive the envelope. 

nShape int Specifies an index to an OEM wave-shape table. 

nRepeat int Specifies the number of repetitions of the wave shape during 


the duration of one note. 


Return Value The return value specifies the result of the function. It is zero if the function is successful. 
If an error occurs, the return value is one of the following values: 
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Value Meaning 
S_SERDRC Invalid repeat count 
S_SERDSH : Invalid shape 
S_SERQFUL Queue full 
SetVoiceNote 
Syntax int SetVoiceNote(nVoice, nValue, nLength, nCdots) 


This function queues a note that has the qualities given by the nValue, nLength, and nCdots 
parameters in the voice queue specified by the nVoice parameter. An error occurs if there is 
insufficient room in the queue. The function always leaves space in the queue for a single 


sync mark. 

Parameter Type/Description 

nVoice int Specifies the voice queue to receive the note. If nVoice is 
out of range, the Set VoiceNote function is ignored. 

nValue int Specifies 1 of 84 possible notes (seven octaves). If nValue 
iS zero, arest is assumed. 

nLength int Specifies the reciprocal of the duration of the note. For ex- 

ample, 1 specifies a whole note, 2 a half note, 4 a quarter note, 

and so on. 

nCdots int Specifies the duration of the note in dots. The duration is 
equal to nLength x (nCdots x 3/2). 

Return Value The return value specifies the result of the function. It is zero if the function is successful. 


If an error occurs, the return value is one of the following values: 


Value Meaning 
S_SERDCC Invalid dot count 
S_SERDLN Invalid note length 
S_SERDNT _ Invalid note 


S_SERQFUL Queue full 
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SetVoiceQueueSize 


Syntax int SetVoiceQueueSize(nVoice, nBytes) 


This function allocates the number of bytes specified by the nBytes parameter for the voice 
queue specified by the nVoice parameter. If the queue size is not set, the default is 192 
bytes, which is room for about 32 notes. All voice queues are locked in memory. The 
queues cannot be set while music is playing. 


Parameter Type/Description 
nVoice int Specifies a voice queue. | 
nBytes int Specifies the number of bytes in the voice queue. 
Return Value The return value specifies the result of the function. It is zero if the function is successful. 


If an error occurs, the return value is one of the following values: 


Value Meaning 

S_SERMACT Music active 

S_SEROFM Out of memory 
SetVoiceSound 
Syntax int SetVoiceSound(nVoice, lFrequency, nDuration) 


This function queues the sound frequency and duration in the voice queue specified by the 
nVoice parameter. 


Parameter Type/Description 

nVoice int Specifies a voice queue. The first voice queue is numbered 
1. 

lFrequency long Specifies the frequency. The high-order word contains 


the frequency in hertz, and the low-order word contains the frac- 
tional frequency. 


nDuration int Specifies the duration of the sound (in clock ticks). 


Return Value The return value specifies the result of the function. It is zero if the function is successful. 
If an error occurs, the return value is one of the following values: 
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Value Meaning 

S_SERDDR Invalid duration 

S_SERDFQ Invalid frequency 

S_SERDVL Invalid volume 

S_SERQFUL Queue full 
SetVoiceThreshold 


Syntax 


Return Value 


SetWindowExt 
Syntax 


int SetVoiceThreshold(nVoice, nNotes) 


This function sets the threshold level for the given voice. When the number of notes 
remaining in the voice queue goes below that specified in the nNotes parameter, the 
threshold flag is set. If the queue level is below that specified in nNotes when the 
Set VoiceThreshold function is called, the flag is not set. The GetThresholdStatus 
function should be called to verify the current threshold status. 


Parameter Type/Description 
nVoice int Specifies the voice queue to be set. 
nNotes int Specifies the number of notes in the threshold level. 


The return value specifies the result of the function. It is zero if the function is successful. 
It is 1 if the number of notes specified in nNotes is out of range. 


DWORD = SetWindowExt(hDC, X, Y) 


This function sets the x- and y-extents of the window associated with the specified device 
context. The window, along with the device-context viewport, defines how GDI maps 
points in the logical coordinate system to points in the device coordinate system. 


The x- and y-extents of the window define how much GDI must stretch or compress units 
in the logical coordinate system to fit units in the device coordinate system. For example, 
if the x-extent of the window is 2 and the x-extent of the viewport is 4, GDI maps two logi- 
cal units (measured from the x-axis) into four device units. Similarly, if the y-extent of the 
window is 2 and the y-extent of the viewport is —1, GDI maps two logical units (measured 
from the y-axis) into one device unit. 
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The extents also define the relative orientation of the x- and y-axes in both coordinate sys- 
tems. If the signs of matching window and viewport extents are the same, the axes have 
the same orientation. If the signs are different, the orientation is reversed. For example, if 
the y-extent of the window is 2 and the y-extent of the viewport is —-1, GDI maps the posi- 
tive y-axis in the logical coordinate system to the negative y-axis in the device coordinate 
system. If the x-extents are 2 and 4, GDI maps the positive x-axis in the logical coordinate 
system to the positive x-axis in the device coordinate system. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
X ' int Specifies the x-extent (in logical units) of the window. 
Y int Specifies the y-extent (in logical units) of the window. 
Return Value The return value specifies the previous extents of the window (in logical units). The y-ex- 


tent is in the high-order word; the x-extent is in the low-order word. If an error occurs, the 
return value is zero. 


Comments When the following mapping modes are set, calls to the SetWindowExt and Set View- 
portExt functions are ignored: 


= MM_HIENGLISH 
= MM_HIMETRIC 

= MM_LOENGLISH 
= MM_LOMETRIC 
= MM_TEXT 

= MM_TWIPS 


When MM_ISOTROPIC mode is set, an application must call the SetWindowExt func- 
tion before calling Set ViewportExt. 


SetWindowLong . 
Syntax LONG  SetWindowLong(hWnd, nIndex, dwNewLong) 


This function changes an attribute of the window specified by the hWnd parameter. 
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Return Value 


Comments 


SetWindowOrg 


Syntax 


Parameter Type/Description 

hWnd HWND Identifies the window. 

nIndex int Specifies the byte offset of the attribute to be changed. It may 
also be one of the following values: 
Value Meaning 
GWL_EXSTYLE Sets a new extended window style. 
GWL_STYLE Sets a new window Style. 
GWL_WNDPROC Sets a new long pointer to the | 


window procedure. 


dwNewLong DWORD _ Specifies the replacement value. 


The return value specifies the previous value of the specified long integer. 


If the SetWindowLong function and the GWL_WNDPROC index are used to set a new 
window function, that function must have the window-function form and be exported in 
the module-definition file of the application. For more information, see the RegisterClass 
function, earlier in this chapter. 


Calling SetWindowLong with the GCL_WNDPROC index creates a subclass of the 
window class used to create the window. See Chapter 1, “Window Manager Interface Func- 
tions,” for more information on window subclassing. An application should not attempt to 
create a window subclass for standard Windows controls such as combo boxes and but- 
tons. 


To access any extra four-byte values allocated when the window-class structure was 
created, use a positive byte offset as the index specified by the n/Jndex parameter, starting 
at zero for the first four-byte value in the extra space, 4 for the next four-byte value and so 
on. 


DWORD SetWindowOrg(iDC, X, Y) 


This function sets the window origin of the specified device context. The window, along 
with the device-context viewport, defines how GDI maps points in the logical coordinate 
system to points in the device coordinate system. 


The window origin marks the point in the logical coordinate system from which GDI maps 
the viewport origin, a point in the device coordinate system specified by the SetWindow- 
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Org function. GDI maps all other points by following the same process required to map 
the window origin to the viewport origin. For example, all points in a circle around the 
point at the window origin will be in a circle around the point at the viewport origin. Simi- 
larly, all points in a line that passes through the window origin will be in a line that passes 
through the viewport origin. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
X int Specifies the logical x-coordinate of the new origin of the 
window. 
Y int Specifies the logical y-coordinate of the new origin of the 
window. 
Return Value The return value specifies the previous origin of the window. The previous y-coordinate is 


in the high-order word; the previous x-coordinate is in the low-order word. 


SetWindowPos 
Syntax void SetWindowPos(hWnd, hWndInsertAfter, X, Y, cx, cy, wF lags) 


This function changes the size, position, and ordering of child, pop-up, and top-level 
windows. Child, pop-up, and top-level windows are ordered according to their appearance 
on the screen; the topmost window receives the highest rank, and it is the first window in 
the list. This ordering is recorded in a window list. 


Parameter Type/Description 

hWnd HWND Identifies the window that will be positioned. 

hWndInsertAfter HWND Identifies a window in the window-manager’s list 
that will precede the positioned window. 

X int Specifies the x-coordinate of the window’s upper-left 
corner. 

y: int Specifies the y-coordinate of the window’s upper-left 
corner. 

cx int Specifies the new window’s width. 


cy int Specifies the new window’s height. 
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Return Value 


Comments 


Parameter Type/Description 


wFlags WORD Specifies one of eight possible 16-bit values that af- 
fect the sizing and positioning of the window. It must be one of 
the following values: 


Value Meaning 


SWP_DRAWFRAME Draws a frame (defined in the 
window’s class description) 
around the window. 


SWP_HIDEWINDOW Hides the window. 
SWP_NOACTIVATE Does not activate the 
window. 
SWP_NOMOVE Retains current position (ig- 
nores the x and y parameters). 
SWP_NOSIZE Retains current size (ignores 
the cx and cy parameters). 
SWP_NOREDRAW Does not redraw changes. 
SWP_NOZORDER Retains current ordering (ig- 
nores the hWndInsertAfter 
parameter). 
SWP_SHOWWINDOW Displays the window. 


None. 


If the SWP_NOZORDER flag is not specified, Windows places the window identified by 
the hWnd parameter in the position following the window identified by the hWndInser- 
tAfter parameter. If hWndInsertAfter is NULL, Windows places the window identified by 
hWnd at the top of the list. If hWndInsertAfter is set to 1, Windows places the window iden- 
tified by hWnd at the bottom of the list. 


If the SWP_SHOWWINDOW or the SWP_HIDEWINDOW flags are set, scrolling and 
moving cannot be done simultaneously. 


All coordinates for child windows are relative to the upper-left corner of the parent 
window’s client area. 


4-419 setWindowsHook 
SetWindowsHook 
Syntax FARPROC  SetWindowsHook(nFilterType, lpFilterFunc) 


Return Value 


Comments 


This function installs a filter function in a chain. A filter function processes events before 
they are sent to an application’s message loop in the WinMain function. A chain is a linked 
list of filter functions of the same type. 


Parameter Type/Description 


nFilterType int Specifies the system hook to be installed. It can be any one of 
the following values: 


Value Meaning 

WH_CALLWNDPROC Installs a window-function fil- 
ter. 

WH_GETMESSAGE Installs a message filter. 

WH_JOURNALPLAYBACK Installs a journaling playback 
filter. 

WH_JOURNALRECORD Installs a journaling record fil- 
ter. 

WH_KEYBOARD Installs a keyboard filter. 

WH_MSGFILTER - Installs a message filter. 

WH_SYSMSGFILTER Installs a system-wide message 
filter. 


JIpFilterFunc FARPROC Is the procedure-instance address of the filter function 


to be installed. See the following “Comments” section for details. 


The return value points to the procedure-instance address of the previously installed filter 
(if any). It is NULL if there is no previous filter. The application or library that calls the 
SetWindowsHook function should save this return value in the library’s data segment. 
The fourth argument of the DefHookProc function points to the location in memory where 
the library saves this return value. 


The WH_CALLWNDPROC hook will affect system performance. It is supplied for debug- 
ging purposes only. 


The system hooks are a shared resource. Installing a hook affects all applications. Most 
hook functions must be in libraries. The only exception is WH_MSGFILTER, which is 
task-specific. System hooks should be restricted to special-purpose applications or as a 
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development aid during debugging of an application. Libraries that no longer need the 
hook should remove the filter function. 


To install a filter function, the SetWindowsHook function must receive a procedure-in- 
stance address of the function, and the function must be exported in the library’s module- 
definition file. Libraries can pass the procedure address directly. Tasks must use 
MakeProclInstance to get a procedure-instance address. Dynamic-link libraries must use 
GetProcAddress to get a procedure-instance address. 


The following section describes how to support the individual hook functions. 


WH_CALLWNDPROC 


Windows calls the WH_CALLWNDPROC filter function whenever the SendMessage 
function is called. Windows does not call the filter function when the PostMessage func- 
tion is called. 


The filter function must use the Pascal calling convention and must be declared FAR. The 
filter function must have the following form: 


Filter Function 


void FAR PASCAL FilterFunc(nCode, wParam, (Param) 
int nCode; 

WORD wParam; 

DWORD /Param; 


FilterFunc is a placeholder for the application- or library-supplied function name. The ac- 
tual name must be exported by including it in an EXPORTS statement in the library’s 
module-definition file. 


Parameter Description 


nCode Specifies whether the filter function should process the message or 
call the DefHookProc function. If the nCode parameter is less than 
zero, the filter function should pass the message to DefHookProc 
without further processing. 


wParam Specifies whether the message is sent by the current task. It is non- 
zero if the message is sent; otherwise, it is NULL. 


lParam Points to a data structure that contains details about the message in- 
tercepted by the filter. The following shows the order, type, and 
description of each field of the data structure: 
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WH_GETMESSAGE 


Parameter Description 
Field Type/Description 
hlParam WORD Contains the high-order word of the 
lParam parameter of the message received by 
the filter. 
lParam WORD Contains the low-order word of the 
/Param parameter of the message received by 
the filter. 
wParam WORD = Contains the wParam parameter of 
the message received by the filter. 
wMsg WORD Contains the message received by 
the filter. 
hWnd WORD Contains the window handle of the 
window that is to receive the message. 
Comments 


The WH_CALLWNDPROC filter function can examine or modify the message as desired. 
Once it returns control to Windows, the message, with any modifications, is passed on to 
the window function. The filter function does not require a return value. 


Windows calls the WH_GETMESSAGE filter function whenever the GetMessage func- 
tion is called. Windows calls the filter function immediately after GetMessage has re- 
trieved a message from an application queue. The filter function must use the Pascal 
calling convention and must be declared FAR. The filter function must have the following 
form: 


Filter Function 


void FAR PASCAL FilterFunc(nCode, wParam, lParam) 
int nCode; 

WORD wParam; 

DWORD /Param; 


FilterFunc is a placeholder for the library-supplied function name. The actual name must 
be exported by including it in an EXPORTS statement in the library’s module-definition 
file. 
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Parameter Description 


nCode Specifies whether the filter function should process the message or 
call the DefHookProc function. If the nCode parameter is less than 
zero, the filter function should pass the message to DefHookProc 
without further processing. 


wParam Specifies a NULL value. 
lParam Points to a message structure. 
Comments 


The WH_GETMESSAGE filter function can examine or modify the message as desired. 
Once it returns control to Windows, the GetMessage function returns the message, with 
any modifications, to the application that originally called it. The filter function does not 
require a return value. 


WH_JOURNALPLAYBACK 


Windows calls the WH_JOURNALPLAYBACK filter function whenever a request for an 
event message is made. The function is intended to be used to supply a previously re- 
corded event message. 


The filter function must use the Pascal calling convention and must be declared FAR. The 
filter function must have the following form: 


Filter Function 


DWORD FAR PASCAL FilterFunc(nCode, wParam, lParam); 
int nCode; 

WORD wParam; 

DWORD /Param; 


FilterFunc is a placeholder for the library-supplied function name. The actual name must 
be exported by including it in an EXPORTS statement in the library’s module-definition 


file. 
Parameter Description 
nCode Specifies whether the filter function should process the message or 


call the DefHookProc function. If the nCode parameter is less then 
zero, the filter function should pass the message to DefHookProc 
without further processing. 
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Parameter Description 

wParam Specifies a NULL value. 

lParam Points to the message being processed by the filter function. 
Comments 


The WH_JOURNALPLAYBACK function should copy an event message to the /Param 
parameter. The message must have been previously recorded by using the WH_JOUR- 
NALRECORD filter. It should not modify the message. The return value should be the 
amount of time (in clock ticks) Windows should wait before processing the message. This 
time can be computed by calculating the difference between the time fields in the current 
and previous event messages. If the function returns zero, the message is processed imme- 
diately. Once it returns control to Windows, the message continues to be processed. If the 
nCode parameter is HC_SKIP, the filter function should prepare to return the next re- 
corded event message on its next call. 


While the WH_JOURNALPLAYBACK function is in effect, Windows ignores all mouse 
and keyboard input. 


WH_JOURNALRECORD 


Windows calls the WH_JOURNALRECORD filter function whenever it processes a 
message from the event queue. The filter can be used to record the event for later playback. 


The filter function must use the Pascal calling convention and must be declared FAR. The 
filter function must have the following form: 


Filter Function 


void FAR PASCAL FilterFunc(nCode, wParam, lParam); 
int nCode; 

WORD wParam; 

DWORD /Param; 


FilterFunc is a placeholder for the library-supplied function name. The actual name must 
be exported by including it in an EXPORTS statement in the library’s module-definition 
file. 


Parameter Description 


nCode Specifies whether the filter function should process the message or 
call the DefHookProc function. If the nCode parameter is less than 
zero, the filter function should pass the message to DefHookProc 
without further processing. 
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WH_KEYBOARD 


Parameter Description 

wParam Specifies a NULL value. 
IParam Points to a message structure. 
Comments 


The WH_JOURNALRECORD function should save a copy of the event message for later 
playback. It should not modify the message. Once it returns control to Windows, the 
message continues to be processed. The filter function does not require a return value. 


Windows calls the WH_KEYBOARD filter function whenever the application calls the 
GetMessage or PeekMessage function and there is a keyboard event (WM_KEYUP or 
WM_KEYDOWN) to process. 


The filter function must use the Pascal calling convention and must be declared FAR. The 
filter function must have the following form: 


Filter Function 


int FAR PASCAL FilterFunc(nCode, wParam, lParam) 
int nCode; 

WORD wParam; 

DWORD /Param; 


FilterFunc is a placeholder for the library-supplied function name. The actual name must 
be exported by including it in an EXPORTS statement in the library’s module-definition 
file. 


Parameter Description 


nCode Specifies whether the filter function should process the message or call 
the DefHookProc function. If this value is HC_NQOREMOVE, the 
application is using the PeekMessage function with the PM_NO- 
REMOVE option and the message will not be removed from the 
system queue. If this value is less than zero, the filter function should 
pass the message to DefHookProc without further processing. 


wParam Specifies the virtual-key code of the given key. 


[Param Specifies the repeat count, scan code, key-transition code, previous 
key state, and context code, as shown in the following list. Bit 1 is the 
low-order bit: 
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WH_MSGFILTER 


Parameter Description 
Bit Value 
0-15 (low-order word) Repeat count (the number of times 


the keystroke is repeated as a result 
of the user holding down the key). 


16-23 (low byte of high- Scan code (OEM-dependent value). 
order word) 


24 Extended key (1 if it is an extended 
key). 

25-26 Not used. 

27-28 (Context code (1 if Used internally by Windows. 


the ALT key was held down 
while the key was pressed, 0 


otherwise) - 

30 Previous key state (1 if the key was 
held down before the message was 
sent, 0 if the key was up). 

31 Transition state (1 if the key is being 

' released, O if the key is being 
pressed). 


Return Value 


The return value specifies what should happen to the message. It is zero if the message 
should be processed by Windows; it is 1 if the message should be discarded. 


Windows calls the WH_MSGFILTER filter function whenever a dialog box, message box, 
or menu has retrieved a message, and before it has processed that message. The filter al- 
lows an application to process or modify the messages. 


NOTE This is the only task-specific filter. A task may install this filter. 


The WH_MSGFILTER filter function must use the Pascal calling convention and must be 
declared FAR. The filter function must have the following form: 
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Filter Function 


int FAR PASCAL FilterFunc(nCode, wParam, lParam ) 
int nCode; 

WORD wParam; 

DWORD /Param; 


FilterFunc is a placeholder for the library- or application-supplied function name. The ac- 
tual name must be exported by including it in an EXPORTS statement in the application’s 
module-definition file. 

Parameter Description 


nCode Specifies the type of message being processed. It must be one of the 
following values: 


Value — Meaning 


MSGF_DIALOGBOX Processing messages inside a dialog- 
box or message-box function. 


MSGF_MENU Processing keyboard and mouse mes- 
sages in a menu. 


If this value is less than zero, the filter function should pass this 
message to DefHookProc without further processing. 


wParam Specifies a NULL value. 


lParam Points to the message structure. 


Return Value 


The return value specifies the outcome of the function. It is nonzero if the hook function 
processes the message. Otherwise, it is zero. 


WH_SYSMSGFILTER 


Windows calls the WH_SYSMSGFILTER filter function whenever a dialog box, message 
box, or menu has retrieved a message and before it has processed that message. The filter 
allows an application to process or modify messages for any application in the system. 


The filter function must use the Pascal calling convention and must be declared FAR. The 
filter function must have the following form: 
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_ Filter Function 


int FAR PASCAL FilterFunc(nCode, wParam, lParam ) 
int nCode; 

WORD wParam; 

DWORD /Param; 


FilterFunc is a placeholder for the library-supplied function name. The actual name must 
be exported by including it in an EXPORTS statement in the library’s module-definition 


file. 
Parameter Description 
nCode Specifies the type of message being processed. It must be one of the 
following values: 
Value Meaning 
MSGF_DJIALOGBOX Processing messages inside the 
DialogBox function. 
MSGF_MENU Processing keyboard and mouse 
messages in menu. 
MSGF_MESSAGEBOX Processing messages inside the 
MessageBox function. 
If this value is less than zero, the filter function should pass the 
message to DefHookProc without further processing. 
wParam Specifies a NULL value. 
lParam Points to the message structure. 


Return Value 


The return value specifies the outcome of the function. It is nonzero if the hook function 
processes the message. Otherwise, it is zero. 


SetWindowText 
Syntax void SetWindowText(hWnd, IpString) 
This function sets the given window’s caption title (if one exists) to the string pointed to by 


the /pString parameter. If the hWnd parameter is a handle to a control, the SetWindowText 
function sets the text within the control instead of within the caption. 
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Parameter Type/Description 
hWnd HWND Identifies the window or control whose text is to be 
changed. 
[pString LPSTR Points to a null-terminated character string. 
Return Value None. 
SetWindowWord 
Syntax WORD Set WindowWord(hWnd, nIndex, wNewWord) 


This function changes an attribute of the window specified by the hWnd parameter. 


Parameter Type/Description 
hWnd HWND Identifies the window to be modified. 
nIndex int Specifies the byte offset of the word to be changed. It can also be 


one of the following values: 


Value Meaning 


GWW_HINSTANCE Instance handle of the module that 
owns the window. 


GWW_ID Control ID of the child window. 
wNewWord WORD Specifies the replacement value. 


Return Value The return value specifies the previous value of the specified word. 


Comments To access any extra two-byte values allocated when the window-class structure was 
created, use a positive byte offset as the index specified by the n/ndex parameter, starting 
at zero for the first two-byte value in the extra space, 2 for the next two-byte value and so 
on. 
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ShowCaret 


ShowCaret 
Syntax 


Return Value 


Comments 


ShowCursor 
Syntax . 


void ShowCaret(hWna) 


This function shows the caret on the display at the caret’s current position. Once shown, 
the caret begins flashing automatically. 


The ShowCaret function shows the caret only if it has a current shape and has not been 
hidden two or more times in a row. If the caret is not owned by the given window, the caret 
is not shown. If the hWnd parameter is NULL, the SetCaret function shows the caret only 
if it is owned by a window in the current task. 


Hiding the caret is accumulative. If the HideCaret function has been called five times in a 
row, ShowCaret must be called five times to show the caret. 


Parameter Type/Description 


hWnd HWND Identifies the window that owns the caret, or is NULL to 
specify indirectly the owner window in the current task. 


None. 


The caret is a shared resource. A window should show the caret only when it has the input 
focus or is active. 


int ShowCursor(bShow) 


This function shows or hides the cursor. The ShowCursor function actually sets an inter- 
nal display counter that determines whether the cursor should be displayed. If the bShow 
parameter is nonzero, ShowCursor adds one to the display count. If bShow is zero, the dis- 
play count is decreased by one. The cursor is displayed only if the display count is greater 
than or equal to zero. Initially, the display count is zero if a mouse is installed. Otherwise, 
itis -1. 


Parameter Type/Description 


bShow BOOL Specifies whether the display count is to be increased or 
decreased. The display count is increased if bShow is nonzero. Other- 
wise, it is decreased. 
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Return Value The return value specifies the new display count. 


Comments The cursor is a shared resource. A window that hides the cursor should show the cursor 
before the cursor leaves its client area, or before the window relinquishes control to 
another window. 


ShowOwnedPopups 
Syntax void ShowOwnedPopups(hWnd, fShow) 


This function shows or hides all pop-up windows that are associated with the hWnd para- 
meter. If the {Show parameter is nonzero, all hidden pop-up windows are shown; if fShow 
is zero, all visible pop-up windows are hidden. 


Parameter Type/Description 


hWnd HWND Identifies the window that owns the pop-up windows that 
are to be shown or hidden. 


Show -~ BOOL Specifies whether or not pop-up windows are hidden. It is 
nonzero if all hidden pop-up windows should be shown; it is zero if 
all visible pop-up windows should be hidden. 


Return Value None. 


ShowScerollBar 
Syntax void ShowScrollBar(iWnd, wBar, bShow) 


This function displays or hides a scroll bar, depending on the value of the bShow parame- 
ter. If bShow is nonzero, the scroll bar is displayed; if bShow is zero, the scroll bar is hid- 


den. 

Parameter Type/Description 

hWnd HWND Identifies a window that contains a scroll bar in its non- 
client area if the wBar parameter is SB_HORZ, SB_VERT, or 
SB_BOTH. If wBar is SB_CTL, hWnd identifies a scroll-bar control. 

wBar WORD _ Specifies whether the scroll bar is a control or part of a 


window’s nonclient area. If it is part of the nonclient area, wBar also 
indicates whether the scroll bar is positioned horizontally, vertically, or 
both. It must be one of the following values: 
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ShowWindow 


Return Value 


Comments 


ShowWindow 
Syntax 


Return Value 


Comments 


Parameter Type/Description 
Value Meaning 
SB_BOTH Specifies the window’s horizontal and vertical scroll 


bars. 


SB_CTL Specifies that the scroll bar is a control. 
SB_HORZ Specifies the window’s horizontal scroll bar. 
SB_VERT Specifies the window’s vertical scroll bar. 

bShow BOOL Specifies whether or not Windows hides the scroll bar. If 


bShow is zero, the scroll bar is hidden. Otherwise, the scroll bar is dis- 


played. 


None. 


An application should not call this function to hide a scroll bar while processing a scroll- 


bar notification message. 


BOOL ShowWindow(hWnd, nCmdShow) 


This function displays or removes the given window, as specified by the nCmdShow para- 


meter. 

Parameter Type/Description 

hWnd HWND Identifies the window. 

nCmdShow int Specifies how the window is to be shown. It must be one of the 


values shown in Table 4.18, ‘““Window States.” 


The return value specifies the previous state of the window. It is nonzero if the window 
was previously visible. It is zero if the window was previously hidden. 


The ShowWindow function must be called only once per program with the nCmdShow 
parameter from the WinMain function. Subsequent calls to ShowWindow must use one of 
the values listed above, instead of one specified by the nCmdShow parameter from the 
WinMain function. Table 4.18 lists the values for the nCmdShow parameter: 


SizeofResource 
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SizeofResource 


Syntax 


Return Value 


Table 4.18 


Window States 


Value 


SW_HIDE 


Meaning 


Hides the window and passes activation to another 


SW_MINIMIZE 


SW_RESTORE 
SW_SHOW 


SW_SHOWMAXIMIZED 


SW_SHOWMINIMIZED 
SW_SHOWMINNOACTIVE 


SW_SHOWNA 


SW_SHOWNOACTIVATE 


SW_SHOWNORMAL 


window. 


Minimizes the specified window and activates the top- 
level window in the window-manager’s list. 


Same as SW_SHOWNORMAL. 


Activates a window and displays it in its current size and 
position. 

Activates the window and displays it as a maximized 
window. 

Activates the window and displays it as iconic. 


Displays the window as iconic. The window that is cur- 
rently active remains active. 


Displays the window in its current state. The window that 
is currently active remains active. . 


Displays a window in its most recent size and position. 
The window that is currently active remains active. 


Activates and displays a window. If the window is min- 
imized or maximized, Windows restores it to its original 
size and position. 


WORD _ SizeofResource(/nstance, hResInfo) 


This function supplies the size (in bytes) of the specified resource. It is typically used with 
the AccessResource function to prepare memory to receive a resource from the file. 


Parameter Type/Description 

hInstance HANDLE Identifies the instance of the module whose executable 
file contains the resource. 

hResInfo HANDLE Identifies the desired resource. This handle is assumed 


to have been created by using the FindResource function. 


The return value specifies the number of bytes in the resource. It is zero if the resource can- 


not be found. 
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Comments The value returned may be larger than the actual resource due to alignment. An application 
should not rely upon this value for the exact size of a resource. 

StartSound 

Syntax int StartSound( ) 


Return Value 


StopSound - 


Syntax 


Return Value 


StretchBlt 
Syntax 


This function starts play in each voice queue. The StartSound function is not destructive, 
so it may be called any number of times to replay the current queues. 


This function has no parameters. 


Although the return-value type is integer, its contents should be ignored. 


int StopSound( ) 


This function stops playing all voice queues, then flushes the contents of the queues. The 
sound driver for each voice is turned off. 


This function has no parameters. 


Although the return-value type is integer, its contents should be ignored. 


BOOL StretchBlt(ADestDC, X, Y, nWidth, nHeight, hSrcDC, XSrc, YSrc, nSrcWidth, 
nSrcHeight, dwRop) 


This function moves a bitmap from a source rectangle into a destination rectangle, stretch- 
ing or compressing the bitmap if necessary to fit the dimensions of the destination 
rectangle. The StretchBlt function uses the stretching mode of the destination device con- 
text (set by the SetStretchBltMode function) to determine how to stretch or compress the 
bitmap. 


StretchBIt moves the bitmap from the source device given by the hSrcDC parameter to 
the destination device given by the hDestDC parameter. The XSrc, ¥Src, nSrcWidth, and 
nSrcHeight parameters define the origin and dimensions of the source rectangle. The X, Y, 
nWidth, and nHeight parameters give the origin and dimensions of the destination 
rectangle. The raster operation specified by the dwRop parameter defines how the source 
bitmap and the bits already on the destination device are combined. 
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StretchBlt creates a mirror image of a bitmap if the signs of the nSrcWidth and nWidth or 
nSrcHeight and nHeight parameters differ. If nSrcWidth and nWidth have different signs, 
the function creates a mirror image of the bitmap along the x-axis. If nSrcHeight and 
nHeight have different signs, the function creates a mirror image of the bitmap along the y- 


axis. 

Parameter Type/Description 

hDestDC HDC Identifies the device context to receive the bitmap. 

Xx int Specifies the logical x-coordinate of the upper-left corner of the 
destination rectangle. 

| a int Specifies the logical y-coordinate of the upper-left corner of the 
destination rectangle. 

nWidth int Specifies the width (in logical units) of the destination 

' rectangle. 

nHeight int Specifies the height (in logical units) of the destination 
rectangle. 

hSrcDC HDC Identifies the device context that contains the source bitmap. 

XSrc int Specifies the logical x-coordinate of the upper-left corner of the 
source rectangle. 

YSrc int Specifies the logical y-coordinate of the upper-left corner of the 
source rectangle. 

nSrcWidth int Specifies the width (in logical units) of the source rectangle. 

nSrcHeight int Specifies the height (in logical units) of the source rectangle. 

dwRop DWORD _ Specifies the raster operation to be performed. Raster 
operation codes define how GDI combines colors in output opera- 
tions that involve a current brush, a possible source bitmap, and a 
destination bitmap. For a list of raster-operation codes, see the BitBlt 
function, earlier in this chapter. For a complete list of the operations, 
see Chapter 11, “Binary and Ternary Raster-Operation Codes,” in 
Reference, Volume 2. 

Return Value The return value specifies whether the bitmap is drawn. It is nonzero if the pine iS 


drawn. Otherwise, it is zero. 


Comments StretchBlt stretches or compresses the source bitmap in memory, then copies the result to 
the destination. If a pattern is to be merged with the result, it is not merged until the 
stretched source bitmap is copied to the destination. 
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StretchDIBits 


If a brush is used, it is the selected brush in the destination device context. 


The destination coordinates are transformed according to the destination device context; 
the source coordinates are transformed according to the source device context. 


If destination, source, and pattern bitmaps do not have the same color format, StretchBlt 
converts the source and pattern bitmaps to match the destination bitmaps. The foreground 
and background colors of the destination are used in the conversion. 


If StretchBIt must convert a monochrome bitmap to color, it sets white bits (1) to back- 
ground color and black bits (0) to foreground color. To convert color to monochrome, it 
sets pixels that match the background color to white (1), and sets all other pixels to black 
(0). The foreground and background colors of the device context with color are used. 


Not all devices support the StretchBlt function. For more information, see the 
RC_BITBLT capability in the GetDeviceCaps function, earlier in this chapter. 


StretchDIBits 


Syntax 


WORD | StretchDIBits(hDC, DestX, DestY, wDestWidth, wDestHeight, SrcxX, Srey, 
wSrcWidth, wSrcHeight, lpBits, lpBitsInfo, wUsage, dwRop) 


This function moves a device-independent bitmap (DIB) from a source rectangle into a 
destination rectangle, stretching or compressing the bitmap if necessary to fit the dimen- 
sions of the destination rectangle. The StretchDIBits function uses the stretching mode of 
the destination device context (set by the SetStretchBltMode function) to determine how 
to stretch or compress the bitmap. 


StretchDIBits moves the bitmap from the device-independent bitmap specified by the 
IpBits, IpBitsInfo, and wUsage parameters to the destination device specified by the hDC 
parameter. The XSrc, YSrc, wSrcWidth, and wSrcHeight parameters define the origin and di- 
mensions of the source rectangle. The origin of coordinate system of the device-inde- 
pendent bitmap is the lower-left corner. The DestX, DestY, wDestWidth, and wDestHeight 
parameters give the origin and dimensions of the destination rectangle. The origin of the 
coordinates of the destination depends on the current mapping mode of the device context. 
See the SetMapMode function earlier in this chapter for more information on mapping 
modes. 


The raster operation specified by the dwRop parameter defines how the source bitmap and 
the bits already on the destination device are combined. 


StretchDIBits creates a mirror image of a bitmap if the signs of the wSrcWidth and 
wDestWidth or wSrcHeight and wDestHeight parameters differ. If wSrcWidth and nWidth 
have different signs, the function creates a mirror image of the bitmap along the x-axis. If 
wSrcHeight and nHeight have different signs, the function creates a mirror image of the bit- 
map along the y-axis. 


StretchDIBits 


Parameter 


hDC 

DestX 
DestY 
wDestWidth 
wDestHeight 
Srcex 

SrcY 
wSrcWidth 
wSrcHeight 
[pBits 
IpBitsInfo 


wUsage 
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Type/Description 


HDC Identifies the destination device context for a display sur- 
face or memory bitmap. 


WORD _ Specifies the x-coordinate (in logical units) of the origin 
of the destination rectangle. 


WORD _ Specifies the y-coordinate (in logical units) of the origin 
of the destination rectangle. 


WORD _ Specifies the x-extent (in logical units) of the destina- 
tion rectangle. 


WORD Specifies the y-extent (in logical units) of the destina- 
tion rectangle. 


WORD _ Specifies the x-coordinate (in pixels) of the source in 
the DIB. 


WORD _ Specifies the y-coordinate (in pixels) of the source in 
the DIB. 


WORD Specifies the width (in pixels) of the source rectangle in 
the DIB. 


WORD Specifies the height (in pixels) of the source rectangle in 
the DIB. 


LPSTR Points to the DIB bits that are stored as an array of 
bytes. 


LPBITMAPINFO Points to a BITMAPINFO data structure 
that contains information about the DIB. 


WORD _ Specifies whether the bmiColors[ ] fields of the /pBit- 
sInfo parameter contain explicit RGB values or indexes into the 
currently realized logical palette. The wUsage parameter must be 
one of the following values: 


Value Meaning 


DIB_PAL_COLORS The color table consists of an array 
of 16-bit indexes into the currently 


realized logical palette. 


The color table contains literal RGB 


DIB_RGB_COLORS 
values. 
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SwapMouseBution 


Return Value 


Parameter Type/Description 


dwRop DWORD _Specifies the raster operation to be performed. Raster 
. operation codes define how GDI combines colors in output opera- 
tions that involve a current brush, a possible source bitmap, and a 
destination bitmap. For a list of raster-operation codes, see the 
BitBlt function, earlier in this chapter. For a complete list of the 
operations, see Chapter 11, “Binary and Ternary Raster-Operation 
Codes,” in Reference, Volume 2. 


The return value is the number of scan lines copied. 


Comments This function also accepts a device-independent bitmap specification formatted for 
Microsoft OS/2 Presentation Manager versions 1.1 and 1.2 if the /pBitsInfo parameter 
points to a BITMAPCOREINFO data structure. 

SwapMouseButton 

Syntax BOOL SwapMouseButton(bSwap) 


Return Value 


Comments 


This function reverses the meaning of left and right mouse buttons. If the bSwap parameter 
is TRUE, the left button generates right-button mouse messages and the right button gener- 
ates left-button messages. If bSwap is FALSE, the buttons are restored to their original 
meaning. 


Parameter Type/Description 
bSwap BOOL Specifies whether the button meanings are reversed or — 
restored. 


The return value specifies the outcome of the function. It is TRUE if the fuction reversed 
the meaning of the mouse buttons. Otherwise, it is FALSE. 


Button swapping is provided as a convenience to people who use the mouse with their left 
hands. The SwapMouseButton function is usually called by the control panel only. Al- 
though applications are free to call the function, the mouse is a shared resource and re- 
versing the meaning of the mouse button affects all applications. 


a 
a] 
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SwapRecording 
Syntax void SwapRecording(wFlag) 


When running Microsoft Windows Swap, this function begins or ends analyzing swapping 
behavior. For more information on Swap, see Tools. 


Parameter Type/Description 
wFlag WORD _ Specifies whether Swap is to start or stop analyzing swap- 
ping behavior. The following are acceptable values: 
Value Meaning 
0 Specifies that Swap stop analyzing. 
1 Record swap calls, discard swap returns. 
2 Same as 1, plus calls through thunks. This option 


records a large amount of data. 


Return Value None. 


SwitchStackBack 
Syntax void. SwitchStackBack( ) 


This function returns the stack of the current task to the task’s data segment after it had 
been previously redirected by the SwitchTasksBack function. 


This function has no parameters. 
Return Value None. 


Comments This function preserves the contents of the AX:DX register when it returns. 


SwitchStackTo 
Syntax void SwitchStackTo(wStackSegment, wStackPointer, wStackTop) 


This function changes the stack of the current task to the segment identified by the wStack- 
Segment parameter. 
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SyncAllVoices 


Return Value 


Comments 


SyncAllVoices 
Syntax 


Return Value 


Dynamic-link libraries (DLLs) do not have a stack; instead, a DLL uses the stack of the 
task which calls the library. As a result, DLL functions that assume that the contents of the 
code-segment (CS) and stack-segment (SS) registers are the same will fail. The Switch- 
StackTo function redirects the stack of the task to the data segment of a DLL, permitting 
the DLL to call these functions. SwitchStackTo copies the arguments on the stack of the 
task to the new stack location. 


Parameter Type/Description 

wStackSegment WORD _ Specifies the data segment which is to contain the 
stack. 

wStackPointer WORD Specifies the offset of the beginning of the stack in 


the data segment. 


wStackTop WORD Specifies the offset of the top of the stack from the 
beginning of the stack. 


None. 


A task can call SwitchStackTo before calling a function in a DLL that assumes the CS and 
DS registeres are equal. When the DLL function returns, the task must then call Switch- 
StackBack to redirect its stack to its own data segment. 


A DLL can also call SwitchStackTo before calling a routine that assumes CS and DS are 
equal and then call SwitchStackBack before returning to the task that called the DLL func- 
tion. 


Calls to SwitchStackTo and SwitchStackBack cannot be nested. That is, after calling 
SwitchStackTo, a program must call SwitchStackBack before calling SwitchStackTo 
again. 


int SyncAllVoices( ) 


This function queues a sync mark in each queue. Upon encountering a sync mark in a 
voice queue, the voice is turned off until sync marks are encountered in all other queues. 
This forces synchronization among all voices. 


This function has no parameters. 


The return value specifies the result of the function. It is zero if the function is successful. 
If a voice queue is full, the return value is S_SERQFUL. 


TabbedTextOut 4-440 


TabbedTextOut 


Syntax 


Return Value 


Comments 


long TabbedTextOut(DC, X, Y IpString, nCount, nTabPositions, lpnTabStopPositions, 
nTabOrigin) 


This function writes a character string on the specified display, using the currently selected 
font and expanding tabs to the columns specified in the /pnTabStopP ositions field. 


Parameter Type/Description 

hDC HDC Identifies the device context. 

xX int Specifies the logical x-coordinate of the starting point 
of the string. 

Y int Specifies the logical y-coordinate of the starting point 
of the string. 

lpString LPSTR Points to the character string that is to be drawn. 

nCount — int Specifies the number of characters in the string. 

nTabPositions int Specifies the number of tab-stop positions in the array 


to which the [pnTabStopPositions points. 


IpnTabStopPositions LPINT Points to an array of integers containing the tab- 
stop positions in pixels. The tab stops must be sorted in 
increasing order; back tabs are not allowed. 


nTabOrigin int Specifies the logical x-coordinate of the starting posi- 
tion from which tabs are expanded. 


The return value specifies the dimensions of the string. The height is in the high-order 
word; the width is in the low-order word. 


If the nTabPositions parameter is zero the the IpnTabStopPositions parameter is NULL, 
tabs are expanded to eight average character widths. 


If nTabPositions is 1, the tab stops will be separated by the distance specified by the first 
value in the array to which /pnTabStopPositions points. 


If IpnTabStopPositions points to more than a single value, then a tab stop is set for each 
value in the array, up to the number specified by nTabPositions. 


The nTabOrigin parameter allows an application to call the TabbedTextOut function 
several times for a single line. If the application calls TabbedTextOut more than once 
with the nTabOrigin set to the same value each time, the function expands all tabs relative 
to the position specified by nTabOrigin. 
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TextOut 


TextOut 
Syntax 


Return Value 


Comments 


Throw 
Syntax 


BOOL  TextOut(iDC, X, Y, lpString, nCount) 


This function writes a character string on the specified display, using the currently selected 
font. The starting position of the string is given by the X and Y parameters. 


Parameter Type/Description 

hDC | HDC Identifies the device context. 

X int Specifies the logical x-coordinate of the starting point of the 
string. 

Y int Specifies the logical y-coordinate of the starting point of the 
string. 

IpString LPSTR Points to the character string that is to be drawn. 

nCount int Specifies the number of characters in the string. 


The return value specifies whether or not the string is drawn. It is nonzero if the string is 
drawn. Otherwise, it is zero. 


Character origins are defined to be at the upper-left corner of the character cell. 


By default, the current position is not used or updated by this function. However, an appli- 
cation can call the SetTextAlign function with the wFlags parameter set to TA_UP- 
DATECP to permit Windows to use and update the current position each time the 
application calls TextOut for a given device context. When this flag is set, Windows ig- 
nores the X and Y parameters on subsequent TextOut calls. 


void Throw(/pCatchBuf, nThrowBack) 


This function restores the execution environment to the values saved in the buffer pointed 
to by the /pCatchBuf parameter. The execution environment is the state of all system 
registers and the instruction counter. Execution continues at the Catch function that copied 
the environment pointed to by IpCatchBuf. The nThrowBack parameter is passed as the re- 
turn value to the Catch function. It can be a nonzero value. 
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Parameter Type/Description 
IpCatchBuf LPCATCHBUF Points to an array that contains the execution en- 
vironment. 
nThrowBack int Specifies the value to be returned to the Catch function. 
Return Value None. 


Comments 


ToAscii 


Syntax 


Return Value 


The Throw function is similar to the C run-time LongJmp function (which is incompat- 
ible with the Windows environment). 


int ToAscii(wVirtKey, wScanCode, IlpKeyState, lpChar, wFlags) 


This function translates the virtual-key code specified by the wVirtKey parameter and the 
current keyboard state specified by the /pKeyState parameter to the corresponding ANSI 
character or characters. 


Parameter Type/Description 

wvirtKey WORD Specifies the virtual-key code to be translated. 

wScanCode WORD _ Specifies the “hardware” raw scan code of the key to 
be translated. The high-order bit of this value is set if the key is 
up. 

IpKeyState LPSTR Points to an array of 256 bytes, each of which con- 
tains the state of one key. If the high-order bit of the byte is set 
the key is up. 

IpChar . LPVOID _ Points to a 32-bit buffer which receives the trans- 


lated ANSI character or characters. 


wFlags | WORD The bit 0 flag’s menu display. 


The return value specifies the number of characters copied to the buffer identified by the 
IpChar parameter. The return value is negative if the key was a dead key. Otherwise, it is 
one of the following values: 
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Value Meaning 
2 Two characters were copied to the buffer. This is usually an ac- 
cent and a dead-key character, when the dead key cannot be 
translated otherwise. 
l One ANSI character was copied to the buffer. 
0 The specified virtual key has no translation for the current state 
of the keyboard. 
Comments The parameters supplied to the ToAscii function might not be sufficient to translate the vir- 


tual-key code because a previous dead key is stored in the keyboard driver. 


Typically, ToAscii performs the translation based on the virtual-key code. In some cases, 
however, the wScanCode parameter may be used to distinguish between a key depression 
or a key release. The scan code is used for translating ALT+NUMBER key combinations. 


TrackPopupMenu 


Syntax 


BOOL = TrackPopupMenu(/Menu, wF lags, x, y, nReserved, hWnd, IpReserved) | 


This function displays a “floating” pop-up menu at the specified location and tracks the 
selection of items on the pop-up menu. A floating pop-up menu can appear anywhere on 
the screen. The AMenu parameter specifies the handle of the menu to be displayed; the 
application obtains this handle by calling CreatePopupMenu to create a new pop-up 
menu or by calling GetSubMenu to retrieve the handle of a pop-up menu associated with 
an existing menu item. 


Windows sends messages generated by the menu to the window identified by the hWnd 
parameter. 


Parameter Type/Description 

hMenu HMENU Identifies the pop-up menu to be displayed. 

wF lags WORD Not used. This parameter must be set to zero. 

x int Specifies the horizontal position in screen coordinates of the 


left side of the menu on the screen. 


y int Specifies the vertical position in screen coordinates of the top 
of the menu on the screen. 


nReserved int Is reserved and must be set to zero. 


> 
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Return Value 


Parameter | Type/Description 


hWnd" HWND Identifies the window which owns the pop-up menu. This 
window receives all WM_COMMAND messages from the menu. 


lpReserved - LPVOID _ Is reserved and must be set to NULL. 


The return value specifies the outcome of the function. It is TRUE if the function is 
successful. Otherwise, it is FALSE. 


TranslateAccelerator 


Syntax 


Return Value 


int TranslateAccelerator(iWnd, hAccTable, IpMsg) 


This function processes keyboard accelerators for menu commands. The TranslateAccel- 
erator function translates WM_KEYUP and WM_KEYDOWN messages to WM_COM- 
MAND or WM_SYSCOMMAND messages, if there is an entry for the key in the 
application’s accelerator table. The high-order word of the /Param parameter of the 
WM_COMMAND or WM_SYSCOMMAND message contains the value 1 to differen- 
tiate the message from messages sent by menus or controls. 


WM_COMMAND or WM_SYSCOMMAND messages are sent directly to the window, 
rather than being posted to the application queue. The TranslateAccelerator function does 
not return until the message is processed. 


Accelerator key strokes that are defined to select items from the system menu are trans- 
lated into WM_SYSCOMMAND messages; all other accelerators are translated into 
WM_COMMAND messages. 


Parameter Type/Description 

hWnd HWND Identifies the window whose messages are to be trans- 
lated. 

hAccTable HANDLE Identifies an accelerator table (loaded by using the 


LoadAccelerators function). 


IpMsg LPMSG Points to a message retrieved by using the GetMessage 
or PeekMessage function. The message must be an MSG data struc- 
ture and contain message information from the Windows application 
queue. 


The return value specifies the outcome of the function. It is nonzero if translation occurs. 
Otherwise, it is zero. 
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TranslateMDISysAccel 


Comments 


When TranslateAccelerator returns nonzero (meaning that the message is translated), the 
application should not process the message again by using the TranslateMessage function. 


Commands in accelerator tables do not have to correspond to menu items. 


If the accelerator command does correspond to a menu item, the application is sent 
WM_INITMENU and WM_INITMENUPOPUP messages, just as if the user were trying 
to display the menu. However, these messages are not sent if any of the following condi- 
tions are present: 


= The window is disabled. 
= The menu item is disabled. 
= The command is not in the System menu and the window is minimized. 


= A mouse capture is in effect (for more information, see the SetCapture function, ear- 
lier in this chapter). 


If the window is the active window and there is no keyboard focus (generally true if the 
window is minimized), then WM_SYSKEYUP and WM_SYSKEYDOWN messages are 
translated instead of WM_KEYUP and WM_KEYDOWN messages. 


If an accelerator key stroke that corresponds to a menu item occurs when the window that 
owns the menu is iconic, no WM_COMMAND message is sent. However, if an accel- 
erator key stroke that does not match any of the items on the window’s menu or the Sys- 
tem menu occurs, a WM_COMMAND message is sent, even if the window is iconic. 


TranslateMDISysAccel [3.0] 


Syntax 


BOOL = TranslateMDISysAccel(hWndClient, IpMsg) 


This function processes keyboard accelerators for multiple document interface (MDI) 
child window System-menu commands. The TranslateMDISysAccel function translates 
WM_KEYUP and WM_KEYDOWN messages to WM_SYSCOMMAND messages. The 
high-order word of the /Param parameter of the WM_SYSCOMMAND message contains 
the value 1 to differentiate the message from messages sent by menus or controls. 


Parameter Type/Description 
hWndClient HWND Identifies the parent MDI client window. 


lpMsg LPMSG Points to a message retrieved by using the GetMessage 
; or PeekMessage function. The message must be an MSG data struc- 
ture and contain message information from the Windows application 
queue. 
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Return Value The return value is TRUE if the function translated a message into a system command. 
Otherwise, it is FALSE. 


TranslateMessage 
Syntax BOOL _ TranslateMessage(/pMs¢) 
This function translates virtual-key messages into character messages, as follows: 
=» WM_KEYDOWN/WM_KEYUP combinations produce a WM_CHAR ora 
WM_DEADCHAR message. 
= WM_SYSKEYDOWN/WM_SYSKEYUP combinations produce a WM_SYSCHAR 
ora WM_SYSDEADCHAR message. 


The character messages are posted to the application queue, to be read the next time the 
application calls the GetMessage or PeekMessage function. 


Parameter Type/Description 


IpMsg LPMSG Points to an MSG data structure retrieved through the 
GetMessage or PeekMessage function. The structure contains 
message information from the Windows application queue. 


Return Value The return value specifies the outcome of the function. It is nonzero if the message is trans- 
lated (that is, character messages are posted to the application queue). Otherwise, it is zero. 


Comments The TranslateMessage function does not modify the message given by the IpMsg parame- 
ter. 


TranslateMessage produces WM_CHAR messages only for keys which are mapped to 
ASCII characters by the keyboard driver. 


An application should not call TranslateMessage if the application processes virtual-key 
messages for some other purpose. For instance, an application should not call the Trans- 
lateMessage function if the TranslateAccelerator function returns nonzero. 


TransmitCommChar 
Syntax int TransmitCommChar(nCid, cChar) 


This function marks the character specified by the cChar parameter for immediate trans- 
mission, by placing it at the head of the transmit queue. 
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TransmitCommChar 


Return Value 


Parameter Type/Description 
nCid int Specifies the communication device to receive the character. 


The OpenComm function returns this value. 


cChar char Specifies the character to be transmitted. 


The return value specifies the result of the function. It is zero if the function is successful. 
It is negative if the character cannot be transmitted. A character cannot be transmitted if 
the character specified by the previous TransmitCommChar function has not yet been 


sent. 
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UngetCommChar 


Syntax 


Return Value 


int UngetCommChar(nCid, cChar) 


This function places the character specified by the cChar parameter back into the receive 
queue, making this character the first to be read on a subsequent read from the queue. 


Consecutive calls to the UngetCommChar function are not allowed. The character placed 
back into the queue must be read before attempting to place another. 


Parameter Type/Description 
nCid int Specifies the communication device to receive the character. 
cChar char Specifies the character to be placed in the receive queue. 


The return value specifies the outcome of the function. It is zero if the function is success- 
ful. It is negative if an error occurs. 


UnhookWindowsHook 


Syntax 


BOOL UnhookWindowsHook(xHook, IpfnHook) 


This function removes the Windows hook function pointed to by the [pfnHook parameter 
from a chain of hook functions. A Windows hook function processes events before they are 
sent to an application’s message loop in the WinMain function. 


Parameter Type/Description 


nHook int Specifies the type of hook function removed. It may be one of 
the following values: 


Value Meaning 

WH_CALLWNDPROC Installs a window-function fil- 
ter. 

WH_GETMESSAGE Installs a message filter. 

WH_JOURNALPLAYBACK Installs a journaling playback 
filter. 

WH_JOURNALRECORD Installs a journaling record fil- 
ter. 


WH_KEYBOARD Install a keyboard filter. 
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UnionRect 


Return Value 


UnionRect 
Syntax 


Return Value 


Comments 


UnlockData 
Syntax 


Parameter Type/Description 
Value Meaning 
WH_MSGFILTER Installs a message filter. 
lpfnHook FARPROC Is the procedure-instance address of the hook func- 
tion. 


The return value specifies the outcome of the function. It is nonzero if the hook function is 
successfully removed. Otherwise, it is zero. 


int UnionRect(/pDestRect, IpSrcl Rect, lpSrc2Rect) 


This function creates the union of two rectangles. The union is the smallest rectangle that 
contains both source rectangles. 


Parameter Type/Description 

IpDestRect LPRECT Points to the RECT data structure that is to receive the 
new union. 

IpSrclRect LPRECT Points toa RECT data structure that contains a source 
rectangle. 

IpSrc2Rect LPRECT Points toa RECT data structure that contains a source 
rectangle. 


The return value specifies the outcome of the function. It is nonzero if the union is not 
empty. It is zero if the union is empty. 


Windows ignores the dimensions of an “empty” rectangle, that is, a rectangle that has no 
height or has no width. 


HANDLE  UnlockData(Dummy) 


This macro unlocks the current data segment. It is intended to be used by modules that 
have moveable data segments. 


UnlockResource _ 4-450 


Parameter Type/Description 

Dummy int Is not used; can be set to zero. 
Return Value None. 
UnlockResource 
Syntax BOOL  UnlockResource(/ResData) 


This macro unlocks ‘the resource specified by the hResData parameter and decreases the 
resource’s reference count by one. 


Parameter Type/Description 
hResData HANDLE Identifies the global memory block to be unlocked. 
Return Value The return value specifies the outcome of the macro. It is zero if the block’s reference 


count is decreased to zero. Otherwise, it is nonzero. 


UnlockSegment 
Syntax BOOL  UnlockSegment(wSegment) 


This function unlocks the segment whose segment address is specified by the wSegment 
parameter. If wSegment is —1, the UnlockSegment function unlocks the current data seg- 
ment. 


In real mode, or if the segment is discardable, UnlockSegment decreases the segment’s 
lock count by one. In protected mode, UnlockSegment decreases the lock count of discard- 
able objects and automatic data segments only. The segment is completely unlocked and 
subject to moving or discarding if the lock count is decreased to zero. Other functions also 
can affect the lock count of a memory object. See the description of the GlobalFlags func- 
tion for a list of the functions that affect the lock count. 


In all cases, each time an application calls LockSegment for a segment, it must eventually 
call UnlockSegment for the segment. 
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UnrealizeObject 


Return Value 


Parameter Type/Description 


wSegment WORD Specifies the segment address of the segment to be un- 
locked. If wSegment is —1, the UnlockSegment function unlocks the 
current data segment. 


The return value specifies the outcome of the function. It is zero if the segment’s lock 
count was decreased to zero. Otherwise, the return value is nonzero. An application should 
not rely on the return value to determine the number of times it must subsequently call Un- 
lockSegment for the segment. 


UnrealizeObject 


Syntax 


Return Value 


Comments 


BOOL  UnrealizeObject(iObject) 


If the hObject parameter specifies a brush, this function directs GDI to reset the origin of 
the given brush the next time it is selected. 


If hObject specifies a logical palette, this function directs GDI to realize the palette as 
though it had not previously been realized. The next time the application calls the Realize- 
Palette function for the specified palette, GDI completely remaps the logical palette to the 
system palette. 

Parameter Type/Description 


hObject HANDLE Identifies the object to be reset. 


The return value specifies the outcome of the function. It is nonzero if the function is 
successful. Otherwise, it is zero. 


The UnrealizeObject function should not be used with stock objects. 


This function must be called whenever a new brush origin is set (by means of the 
SetBrushOrigin function). 


A brush specified by the hObject parameter must not be the currently selected brush of any 
display context. 


A palette specified by hObject can be the currently selected palette of a display context. 
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UnregisterClass 


Syntax 


Return Value 


Comments 


BOOL UnregisterClass(/pClassName, hInstance) 


This function removes the window class specified by IpClassName from the window-class 
table, freeing the storage required for the class. 


Parameter Type/Description 


lpClassName LPSTR Points to a null-terminated string containing the class 
name. This class name must have been previously registered by cal- 
ling the RegisterClass function with a valid hInstance field in the 
WNDCLASS structure parameter. Predefined classes, such as dialog- 
box controls, may not be unregistered. 


hInstance HANDLE Identifies the instance of the module that created the 
class. 


The return value is TRUE if the function successfully removed the window class from the 
window-class table. It is FALSE if the class could not be found or if a window exists that 
was created with the class. 


Before using this function, destroy all windows created with the specified class. 


UpdateColors 


Syntax 


Return Value 


w 


int UpdateColors(iDC) 


This function updates the client area of the device context identified by the hDC parameter 
by matching the current colors in the client area to the system palette on a pixel-by-pixel 
basis. An inactive window with a realized logical palette may call UpdateColors as an al- 
ternative to redrawing its client area when the system palette changes. For more informa- 
tion on using color palettes, see Guide to Programming. 


Parameter Type/Description 


hDC HDC Identifies the device context. 


The return value is not used. 
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Comments UpdateColors typically updates a client area faster than redrawing the area. However, be- 
cause UpdateColors performs the color translation based on the color of each pixel before 
the system palette changed, each call to this function results in the loss of some color ac- 
curacy. 


UpdateWindow 
Syntax void UpdateWindow(hWnd) 


This function updates the client area of the given window by sending a WM_PAINT 
message to the window if the update region for the window is not empty. The Update- 
Window function sends a WM_PAINT message directly to the window function of the 
given window, bypassing the application queue. If the update region is empty, no message 


is sent. 
Parameter Type/Description 
hWnd HWND Identifies the window to be updated. 


Return Value None. 
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ValidateCodeSegments 


Syntax 


Return Value 


void ValidateCodeSegments( ) 


This function outputs debugging information to a terminal if any code segments have been 
altered by random memory overwrites. It is only available in the debugging version of 
Windows and is enabled by default. To disable the function, set the EnableSegment- 
Checksum flag in the [kernel] section of WIN.INI to 0. Windows does not validate code 
segments in protected (standard or 386 enhanced) mode. 


This function has no parameters. 


None. 


ValidateFreeSpaces 


Syntax 


Return Value 


Comments 


LPSTR  ValidateFreeSpaces( ) 


This function (available only in the debugging version of Windows) checks free segments 
in memory for valid contents. In the debugging version of Windows, the kernel fills all the 
bytes in free segments with the hexadecimal value CC. This function begins checking for 
valid contents in the free segment with the lowest address, and continues checking until it 
finds an invalid byte or until it has determined that all free space contains valid contents. 
Before calling this function, put the following lines in the WIN_INI file: 


[kernel] 
EnableFreeChecking=1 
EnableHeapChecking=1 


This function has no parameters. 
None. 


Windows sends debugging information to the debugging terminal if an invalid byte is en- 
countered and performs a fatal exit. 


The [kernel] entries in WIN.INI will cause automatic checking of free memory. Before re- 
turning a memory block to the application in response to a GlobalAlloc call, Windows 
checks that memory to make sure it is filled with OCCH. Before a GlobalCompact call, all 
free memory is checked. Note that using this function slows Windows down system-wide 
by about 20%. 
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ValidateRect 
Syntax void ValidateRect(hWnd, IpRect) 


This function validates the client area within the given rectangle by removing the rectangle 
from the update region of the given window. If the JpRect parameter is NULL, the entire 
window is validated. 


Parameter Type/Description 

hWnd HWND Identifies the window whose update region is to be mod- 
ified. 

IpRect LPRECT Points to a RECT data structure that contains the 


rectangle (in client coordinates) to be removed from the update re- 
gion. 


Return Value None. 


Comments The BeginPaint function automatically validates the entire client area. Neither the 
ValidateRect nor ValidateRgn function should be called if a portion of the update 
region needs to be validated before the next WM_PAINT message is generated. 


Windows continues to generate WM_PAINT messages until the current update region is 
validated. 


ValidateRgn 
Syntax void ValidateRgn(hWnd, hRgn) 
This function validates the client area within the given region by removing the region from 


the current update region of the given window. If the /Rgn parameter is NULL, the entire 
window is validated. 


Parameter Type/Description 

hWnd HWND Identifies the window whose update region is to be mod- 
ified. 

hRgn HRGN Identifies a region that defines the area to be removed 


from the update region. 


Return Value None. 


VkKeyScan 
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Comments 


VkKeyScan 
Syntax 


Return Value 


Comments 


Lowes 


The given region must have been created previously by means of a region function (for 
more information, see Chapter 1, “Window Manager Interface Functions”). The region 
coordinates are assumed to be client coordinates. 


int VkKeyScan (cChar) 


This function translates an ANSI character to the corresponding virtual-key code and shift 
state for the current keyboard. Applications which send character by means of 
WM_KEYUP and WM_KEYDOWN messages use this function. 


Parameter Type/Description 
cChar char Specifies the character for which the corresponding virtual- 
key code is to be found. 


The VK_ code is returned in the low-order byte and the shift state in the high-order byte. 
The shift states are: 


Value Meaning 

0 No shift. 

1 Character is shifted. 

2 Character is control character. 

6 Charcter is CONTROL+ALT. 

7 Character is SHIFT+CONTROL+ALT. 
3 


,4,5 A shift key combination that is not used for characters. 


If no key is found that translates to the passed ANSI code, a —1 is returned in both the low- 
order and high-order bytes. 


Translations for the numeric keypad (VK_NUMPADO through VK_DIVIDE) are ignored. 
This function is intended to force a translation for the main keyboard only. 
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WaitMessage 


WaitMessage 
Syntax 


Return Value 


Comments 


void WaitMessage( ) 


This function yields control to other applications when an application has no other tasks to 
perform. The WaitMessage function suspends the application and does not return until a 
new message Is placed in the application’s queue. 


This function has no parameters. 
None. 


The GetMessage, PeekMessage, and WaitMessage functions yield control to other appli- 
cations. These calls are the only way to let other applications run. If your application does 
not call any of these functions for long periods of time, other applications cannot run. 


When GetMessage, PeekMessage, and WaitMessage yield control to other applications, 
the stack and data segments of the application calling the function may move in memory to 
accommodate the changing memory requirements of other applications. If the application 
has stored long pointers to objects in the data or stack segment (that is, global or local vari- 
ables), these pointers can become invalid after a call to GetMessage, PeekMessage, or 
WaitMessage. 


WaitSoundState 


Syntax 


int WaitSoundState(nState) 


This function waits until the play driver enters the specified state. 


Parameter Type/Description 


nState int Specifies the state of the voice queues. It can be any one of 
the following values: 


Value Meaning 

S_ALLTHRESHOLD All voices have reached threshold. 

S_QUEUEEMPTY All voice queues are empty and 
sound drivers turned off. 

S_THRESHOLD A voice queue has reached thre- 


shold, and returns voice. 


WindowFromPoint 4-458 


Return Value — 


The return value specifies the result of the function. It is zero if the function is successful. - 
If the state is not valid, the return value is S_SERDST. 


WindowFromPoint 


Syntax 


Return Value 


WinExec 


Syntax 


HWND_ WindowFromPoint(Point) 


This function identifies the window that contains the given point; Point must specify the 
screen coordinates of a point on the screen. 


Parameter Type/Description 
Point POINT Specifies a POINT data structure that defines the point to 
be checked. 


The return value identifies the window in which the point lies. It is NULL if no window ex- 
ists at the given point. 


WORD WinExec(/pCmdLine, nCmdShow) 


This function executes the Windows or non-Windows application identified by the 
lpCmdLine parameter. The nCmdShow parameter specifies the initial state of the applica- 
tion’s main window when it is created. 


Parameter Type/Description 


IpCmdLine LPSTR Points to a null-terminated character string that contains 
the command line (filename plus optional parameters) for the applica- 
tion to be executed. If the /pCmdLine string does not contain a 
directory path, Windows will search for the executable file in this 
order: 


1. The current directory 


2. The Windows directory (the directory containing WIN.COM); the 
GetWindowsDirectory function obtains the pathname of this 
directory 


3. The Windows system directory (the directory containing such sys- 
tem files as KERNEL.EXE); the GetSystemDirectory function 
obtains the pathname of this directory 
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WinExec 


Return Value 


Parameter 


nCmdShow 


Type/Description 
4. The directories listed in the PATH environment variable 
5. The list of directories mapped in a network 


If the application filename does not contain an extension, then .EXE 
is assumed. 


int Specifies how a Windows application window is to be shown. 
See the description of the ShowWindow function for a list of the 
acceptable values for the nCmdShow parameter. For a non-Windows 
application, the PIF file, if any, for the application determines the 
window state. 


The return value specifies whether the function was successful. If the function was success- 
ful, the return value is greater than 32. Otherwise, it is a value less than 32 that specifies 
the error. The following list describes the error values returned by this function: 


Value 


0 
2 
3 
5 
6 


17 


Meaning 

Out of memory. 

File not found. 

Path not found. 

Attempt to dynamically link to a task. 

Library requires separate data segments for each task. 
Incorrect Windows version. . 
Invalid .EXE file (Mon-Windows .EXE or error in .EXE image). 
OS/2 application. 

DOS 4.0 application. 

Unknown .EXE type. 


Attempt in protected (standard or 386 enhanced) mode to load an 
.EXE created for an earlier version of Windows. 


Attempt to load a second instance of an .EXE containing multiple, 
writeable data segments. 


Attempt in large-frame EMS mode to load a second instance of an 
application that links to certain nonshareable DLLs already in use. 
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Value Meaning 
18 Attempt in real mode to load an application marked for protected 
mode only. 
Comments The LoadModule function provides an alternative method for executing a program. 
WinHelp 
Syntax BOOL = WinHelp(iWnd, [pHelpFile, wCommand, dwData) 


This function invokes the Windows Help application and passes optional data indicating 
the nature of the help requested by the application. The application specifies the name and, 
where required, the directory path of the help file which the Help application is to display. 
See Tools for information on creating and using help files. 


Parameter Type/Description 
hWnd HWND Identifies the window requesting help. 
lpHelpFile LPSTR Points to a null-terminated string containing the 


directory path, if needed, and the name of the help file which the 
Help application is to display. 


wCommand WORD _Specifies the type of help requested. It may be any one 
of the following values: 
Value Meaning 
HELP_CONTEXT Displays help for a particular con- 


text identified by a 32-bit unsigned 
integer value in dwData. 


HELP_HELPONHELP Displays help for using the help 
application itself. If the wCommand 
parameter is set to HELP_HELP- 
ONHELP, WinHelp ignores the 
[pHelpFile and dwData parameters. 


HELP_INDEX Displays the index of the specified 
help file. An application should use 
this value only for help files with a 
single index. It should not use this 
value with HELP_SETINDEX. 
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Parameter Type/Description 


Value Meaning 


HELP_KEY Displays help for a particular key 
word identified by a string pointed 
to by dwData. 


HELP_MULTIKEY Displays help for a key word in an 
alternate keyword table. 


HELP_QUIT Notifies the help application that 
the specified help file is no longer 
in use. 


HELP_SETINDEX Sets the context specified by the 
dwData parameter as the, current 

index for the help file specified by 
the /pHelpFile parameter. This 
index remains current until the user 
accesses a different help file. To 
help ensure that the correct index re- 
mains set, the application should 
call WinHelp with wCommand set 
to HELP_SETINDEX (with 
dwData specifying the correspond- 
ing context identifier) following 
each call to WinHelp with wCom- 
mand set to HELP_CONTEXT. An 
application should use this value | 
only for help files with more than 
one index. It should not use this 
value with HELP_INDEX. 


dwData ~ DWORD _ Specifies the context or key word of the help re- 

quested. If wCommand is HELP_CONTEXT, dwData is a 32-bit 

- unsigned integer containing a context-identifier number. If wCom- 
mand is HELP_KEY, dwData is a long pointer to a null-terminated 
string that contains a key word identifying the help topic. If wCom- 
mand is HELP_MULTIKEY, dwData is a long pointer to a 
MULTIKEYHELP data structure. Otherwise, dwData is ignored 
and should be set to NULL. 


Return Value The return value specifies the outcome of the function. It is TRUE if the function was 
successful. Otherwise it is FALSE. 
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Comments The application must call WinHelp with wCommand set to HELP_QUIT before closing 
the window that requested the help. The Help application will not actually terminate until 
all applications that have requested help have called WinHelp with wCommand set to 
HELP_QUIT. 


WriteComm 
Syntax int. WriteComm(nCid, IpBuf, nSize) 


This function writes the number of characters specified by the nSize parameter to the com- 
munication device specified by the nCid parameter from the buffer pointed to by the /pBuf 
parameter. 


Parameter Type/Description 


nCid int Specifies the device to receive the characters. The OpenComm 
function returns this value. 


lpBuf LPSTR Points to the buffer that contains the characters to be writ- 
ten. 


nSize int Specifies the number of characters to write. 


Return Value The return value specifies the number of characters actually written. When an error occurs, 
the return value is set to a value less than zero, making the absolute value of the return 
value the actual number of characters written. The cause of the error can be determined by 
using the GetCommError function to retrieve the error code and status. 


Comments The WriteComm function will delete data in the transmit queue if there is not enough 
room in the queue for the additional characters. Applications should check the available 
space in the transmit queue with the GetCommError function before calling Write- 
Comm. Also, applications should use the OpenComm function to set the size of the trans- 
mit queue to an amount no smaller than the size of the largest expected output string. 


WritePrivateProfileString 


Syntax BOOL  WritePrivateProfileString(/pApplicationName, lpKeyName, IpString, 
lpFileName) 


This function copies the character string pointed to by the /pString parameter into the 
specified initialization file. It searches the file for the key named by the JpKeyName para- 
meter under the application heading specified by the [pApplicationName parameter. If 
there is no match, it adds to the user profile a new string entry containing the key name 
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WritePrivateProfileString 


Return Value 


Comments 


and the key value specified by the /pString parameter. If there is a matching key, the func- 
tion replaces that key’s value with /pString. 


Parameter Type/Description 

IpApplicationName LPSTR Points to an application heading in the initialization 
file. 

IpKeyName LPSTR Points to a key name that appears under the applica- 
tion heading in the initialization file. 

IpString LPSTR Points to the string that contains the new key 
value. 

IpFileName LPSTR Points to a null-terminated character string that 


names the initialization file. If /pFileName does not contain a 
fully qualified pathname for the file, this function searches 
the Windows directory for the file. If the file does not exist 
and /pFileName does not contain a fully qualified pathname, 
this function creates the file in the Windows directory. The 
WritePrivateProfileString does not create a file if 
IpFileName contains the fully qualified pathname of a file 
that does not exist. 


The return value specifies the result of the function. It is nonzero if the function is success- 
ful. Otherwise, it is zero. 


An application should use a private (application-specific) initialization file to record infor- 
mation which affects only that application. This improves both the performance of the 
application and Windows itself by reducing the amount of information that Windows must 
read when it accesses the initialization file. 


If there is no application field for pApplicationName, this function creates a new applica- 
tion field and places an appropriate key-value line in that field of the initialization file. 


A string entry in the initialization file has the following form: 


Capplication name] 
keyname = string 


An application can also call WritePrivateProfileString to delete lines from its private in- 
itialization file. If JpString is NULL, the function deletes the entire line identified by the 
IpKeyName parameter. If /pString points to a null string, the function deletes only the 
value; the key name remains in the file. If Jp>KeyName is NULL, the function deletes the 
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entire section identified by the /pApplicationName parameter; however, the function does 
not delete any lines beginning with the semicolon (;) comment character. 


WriteProfileString 
Syntax BOOL  WriteProfileString(/pApplicationName, IpKeyName, IpString) 


This function copies the character string pointed to by the /pString parameter into the 
Windows initialization file, WIN.INI. It searches WIN.INI for the key named by the /pKey- 
Name parameter under the application heading specified by the /pApplicationName para- 
meter. If there is no match, it adds to the user profile a new string entry containing the key 
name and the key value specified by the /pString parameter. If there is a matching key, the 
function replaces that key’s value with /pString. 


Parameter Type/Description 
[pApplicationName LPSTR Points to.an application heading in WIN.INI. 
IpKeyName ~ LPSTR Points to a key name that appears under the appli- 
cation heading WIN.INI. 
IpString LPSTR Points to the string that contains the new key 
value. 
Return Value The return value specifies the result of the function. It is nonzero if the function is success- 


ful. Otherwise, it is zero. 


Comments If there is no match for /pApplicationName, this function creates a new application field 
and adds the string pointed to by /pString. 


A string entry in WIN.INI has the following form: 


[application name] 
keyname = string 


An application can also call WriteProfileString to delete lines from WIN.INI. If /pString 
is NULL, the function deletes the entire line identified by the Jp>KeyName parameter. If 
IpString points to a null string, the function deletes only the value; the key name remains 
in the file. If Jp>KeyName is NULL, the function deletes the entire section identified by the 
lpApplicationName parameter; however, the function does not delete any lines beginning 
with the semicolon (;) comment character. 
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wsprintf 


wsprintf 


Syntax 


Return Value 


Comments 


int wsprintf(/pOutput, lpFormat{, argument]. . .) 


This function formats and stores a series of characters and values in a buffer. Each argu- 
ment (if any) is converted and output according to the corresponding format specification 
in the format string. The function appends a NULL to the end of the characters written, but 
the return value does not include the terminating null character in its character count. 


Parameter Type/Description 


lpOutput LPSTR Points to a null-terminated character string to receive the 
formatted output. 


IpFormat LPSTR Points to a null-terminated character string that contains 
the format-control string. In addition to ordinary ASCII characters, a 
format specification for each argument appears in this string. See the 
following “Comments” section for more information on the format 
specification. 


argument Is one or more optional arguments. The number and type of argument 
parameters depends on the corresponding format-control character 
sequences in /pFormat. 


The return value is the number of characters stored in /pOutput, not counting the terminat- 
ing NULL. If an error occurs, the function returns a value less than the length of IpFormat. 


The format-control string contains format specifications that determine the output format 
for the arguments which follow the /pFormat parameter. Format specifications, discussed 
below, always begin with a percent sign (%). If a percent sign is followed by a character 
that has no meaning, such as a format field, the character is output as is. For example, %% 
produces a single percent-sign character. 


The format-control string is read from left to right. When the first format specification (if 
any) is encountered, it causes the value of the first argument after the format-control string 
to be converted and output according to the format specification. ‘The second format speci- 
fication causes the second argument to be converted and output, and so on. If there are 
more arguments than there are format specifications, the extra arguments are ignored. The 
results are undefined if there are not enough arguments for all of the format specifications. 


A format specification has the following form: 
% (-NF# LON Pwidth]L.precision]type 


Each field of the format specification is a single character or a number signifying a particu- 
lar format option. The type characters, which appear after the last optional format field, de- 
termine whether the associated argument is interpreted as a character, a string, or a 


wsprintf 4-466 


number. The simplest format specification contains only the percent sign and a type 
character (for example, %s). The optional fields control other aspects of the formatting. 
The following shows the optional and required fields and their meaning: 


Field Description 


- ' Pad the output with blanks or zeroes to the right to fill the field 
width, justifying the output to the left. If this field is omitted, the out- 
put is padded to the left, justifying the output to the right. 


# Prefix hexadecimal values with Ox (lowercase) or OX (uppercase). 


Pad the output value with zeroes to fill the field width. If this field is 
omitted, the output value is padded with blank spaces. 


width Output the specified minimum number of characters. The width field 
is a nonnegative integer. The width specification never causes a value 
to be truncated; if the number of characters in the output value is 
greater than the specified width, or if the width field is not present, 
all characters of the value are printed, subject to the precision specifi- 
cation. 


precision Output the specified minimum number of digits. If the number of 
digits in the argument is less than the specified precision, the output 
value is padded on the left with zeroes. The value is not truncated 
when the number of digits exceeds the specified precision. If the 
specified precision is 0, omitted entirely, or if the period ( . ) appears 
without a number following it, the precision is set to 1. 


For strings, output the specified maximum number of characters. 


type Output the corresponding argument as a character, string, or a num- 
ber. This field may be any of the following character sequences: 


Sequence Meaning 


S Insert a string argument referenced by a long 
pointer. The argument corresponding to this 
sequence must be passed as a long pointer 


(LPSTR). 
c Insert a single character argument. 
d,1 Insert a signed decimal integer argument. 
Id, li Insert a long signed decimal integer argument. 
u Insert an unsigned integer argument. 


lu Insert a long unsigned integer argument. 


4-467 wvsprintf 


Field Description 
Sequence Meaning 
x, X Insert an unsigned hexadecimal integer argument 
in lowercase or uppercase. 
Ix, 1X Insert a long unsigned hexadecimal integer argu- 


ment in lowercase or uppercase. 


NOTE Unlike all other Windows functions, wsprintf uses the C calling convention (cdecl), rather than 
the Pascal calling convention. As a result, it is the caller’s responsibility to pop arguments off the stack, 
and arguments are pushed in reverse order (that is, the /pOutput parameter is pushed last, to the 
lowest address). In C-language modules, the C compiler performs this task. 


wvsprintf 
Syntax int wvsprintf(/pOutput, lpFormat, IpArglist) 


This function formats and stores a series of characters and values in a buffer. The items 
pointed to by the argument list are converted and output according to the corresponding 
format specification in the format string. The function appends a NULL to the end of the 


characters written, but the return value does not include the terminating null character in 
its character count. 


Parameter Type/Description 


IpOutput LPSTR Points to a null-terminated character string to receive the 
formatted output. 


lpFormat LPSTR Points to a null-terminated character string that contains 
the format-control string. In addition to ordinary ASCII characters, a 
format specification for each argument appears in this string. See the 
description of the wsprintf function, earlier in this chapter, for more 
information on the format specification. 
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Parameter Type/Description 


IpArglist LPSTR Points to an array of words, each of which specifies an ar- 
guement for the format-control string. The number, type and 
interpretation of the arguments depend on the corresponding format- 
control character sequences in /pFormat. Each character or 
word-sized integer (%c, %d, %x, %i) requires one word in /pArglist. 
Long integers (%ld, %li, %1x) require two words, the low-order word 
of the integer followed by the high-order word. A string (%s) requires 
two words, the offset followed by the segment (which together make 
up a far pointer). 


Return Value The return value is the number of characters stored in /pOutput, not counting the terminat- 
ing NULL. If an error occurs, the function returns a value less than the length of [pFormat. 
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Yield 
Syntax void Yield() 
This function halts the current task and starts any waiting task. 
This function has no parameters. 
Return Value None. 
Comments Applications that contain windows should use a DispatchMessage, PeekMessage, or 


TranslateMessage loop rather than calling the Yield function directly. The PeekMessage 
loop handles message synchronization properly and yields at the appropriate times. 


Part || Windows Messages 


Part 2 provides reference information on Windows messages. Windows mes- 
sages allow Windows applications to communicate with each other and with the 
Windows system within a nonpreemptive multitasking environment. 


CHAPTERS 


5 Messages Overview 
6 Messages Directory 
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This chapter describes groups of related Microsoft Windows messages. Each sec- 
tion states the purpose of the message group, lists the messages in the group, and 
describes each message. Some of the. sections contain additional information. See 
Chapter 1, “Window Manager Interface Functions,” for an explanation of send- 
ing and receiving messages. 


This chapter lists the following categories of Windows messages: 


Window-management messages 
Initialization messages 

Input messages 

System messages 

Clipboard messages 
System-information messages 
Control messages 

Notification messages 
Scroll-bar messages 
Nonclient-area messages 


Multiple document interface messages 


5.1 Window-Management Messages 


Window-management messages are sent by Windows to an application when the 
state of a window changes. The following list briefly describes each window- 
management message: 
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Message 


WM_ACTIVATE 


WM_ACTIVATEAPP 


WM_CANCELMODE 


WM_CHILDACTIVATE 


WM_CLOSE 
WM_CREATE 


WM_CTLCOLOR 


WM_DESTROY 


WM_ENABLE 


WM_ENDSESSION 


WM_ENTERIDLE 


WM_ERASEBKGND 


WM_GETDLGCODE 


Description 


Sent when a window becomes active 
or inactive. 


Sent when the window being acti- 
vated belongs to a different appli- 
cation than the window that was 
previously active. 


Cancels any mode the system is in, 
such as one that tracks the mouse in a 
scroll bar or moves a window. 
Windows sends the WM_CANCEL- 
MODE message when an application 
displays a message box. 


Notifies a child window’s parent 
window when the SetWindowPos 
function moves a child window. 


Sent whenever the window is closed. 


Sent when the CreateWindow func- 
tion is called. 


Sent to the parent window of a prede- 
fined control or message box when 
the control or message box is about 
to be drawn. 


Sent when the Destroy Window func- 
tion is called, after the window has 
been removed from the screen. 


Sent after a window has been enabled 
or disabled. 


Tells an application that has re- 
sponded nonzero to a WM_QUERY- 
ENDSESSION message whether the 
session is actually being ended. 


Informs a window that a dialog box 
or menu is displayed and waiting for 
user action. 


Sent when the window background 
needs to be erased. 


Sent to an input procedure associated 
with a control. 
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Message 


WM_GETMINMAXINFO 


WM_GETTEXT 
WM_GETTEXTLENGTH 


WM_ICONERASEBKGND 


WM_KILLFOCUS 


WM_MENUCHAR 


WM_MENUSELECT 


WM_MOVE 
WM_PAINT 


WM_PAINTICON 


WM_PARENTNOTIFY 


WM_QUERYDRAGICON 
WM_QUERYENDSESSION 


WM_QUERYNEWPALETTE 


Description 


Retrieves the maximized size of the 
window, the minimum or maximum 
tracking size of the window, and the 
maximized position of the window. 


Copies the text that corresponds to a 
window. 


Retrieves the length (in bytes) of the 
text associated with a window. 


Sent to an iconic window with a class 
icon when the background of the icon 
needs to be erased. 


Sent immediately before a window 
loses the input focus. 


Notifies the window that owns the 
menu when the user presses a menu 
mnemonic character that doesn’t 
match any of the predefined mnemon- 
ics in the current menu. 


Notifies a window that the user has 
selected a menu item. 


Sent when a window is moved. 


Sent whenever Windows or an appli- 
cation makes a request to repaint a 
portion of an application’s window. 


Sent whenever Windows or an appli- 
cation makes a request to repaint a 
portion of an application’s minimized 
(iconic) window. 


Sent to the parent of a child window 
when the child window is created or 
destroyed. 


Sent when the user is about to drag a 
minimized (iconic) window. 


Sent when the user chooses the End 
Session command. 


Sent when a window is about to re- 
ceive the input focus to allow it to re- 
alize its logical color palette. 
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Message Description 

WM_QUERYOPEN Sent to an icon when the user re- 
quests that the icon be opened into a 
window. 

WM_QUIT Indicates a request to terminate an 
application. 

WM_SETFOCUS Sent after a window receives the 
input focus. 

WM_SETFONT Changes the font used by a control 
for drawing text. 

WM_SETREDRAW Sets or clears the redraw flag, which - 


determines whether or not updates to 
a control are displayed. 


WM_SETTEXT . Sets the text of a window. 
WM_SHOWWINDOW Sent whenever a window is to be hid- 
den or shown. 
WM_SIZE Sent after the size of a window has 
been changed. 


5.2 Initialization Messages 


Initialization messages are sent by Windows when an application creates a menu 
or dialog box. The following list briefly describes each initialization message: 


Message Description 

WM_INITDIALOG Sent immediately before a dialog box 
is displayed. 

WM_INITMENU Requests that a menu be initialized. 

WM_INITMENUPOPUP _ Sent immediately before a pop-up 


menu is displayed. 


5.3 Input Messages 


Input messages are sent by Windows when an application receives input through 
the mouse, keyboard, scroll bars, or system timer. The following list briefly de- 
scribes each input message: 


Message 


WM_CHAR 


WM_CHARTOITEM 


WM_COMMAND 


WM_DEADCHAR 


WM_HSCROLL 
WM_KEYDOWN 
WM_KEYUP 
WM_LBUTTONDBLCLK 
WM_LBUTTONDOWN 
WM_LBUTTONUP 
WM_MBUTTONDBLCLK 
WM_MBUTTONDOWN 
WM_MBUTTONUP 


WM_MOUSEACTIVATE 


WM_MOUSEMOVE 
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Description 


Results when a WM_KEYUP anda 
WM_KEYDOWN message are trans- 
lated. 


Sent by a list box with the 
LBS_WANTKEYBOARDINPUT 
style to its owner in response to a 
WM_CHAR message. 


Sent when the user selects an item 
from a menu, when a control passes a 
message to its parent window, or 
when an accelerator key stroke is 
translated. 


Results when a.WM_KEYUP and a 
WM_KEYDOWN message are trans- 
lated. 


Sent when the user clicks the horizon- 
tal scroll bar with the mouse. 


Sent when a nonsystem key is 
pressed. 


Sent when a nonsystem key is 
released. 


Sent when the user double-clicks the 
left mouse button. 


Sent when the user presses the left 
mouse button. 


Sent when the user releases the left 
mouse button. 


Sent when the user double-clicks the 
middle mouse button. 


Sent when the user presses the 
middle mouse button. 


Sent when the user releases the 
middle mouse button. 


Sent when the cursor is in an inactive 
window and any mouse button is 
pressed. 


Sent when the user moves the mouse. 
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Message Description 

WM_RBUTTONDBLCLK Sent when the user double-clicks the 
right mouse button. 

WM_RBUTTONDOWN Sent when the user presses the right 
mouse button. 

WM_RBUTTONUP Sent when the user releases the right 
mouse button. 

WM_SETCURSOR Sent when mouse input is not cap- 


tured and the mouse causes cursor 
movement within a window. 


WM_TIMER Sent when the time limit set for a 
given timer has elapsed. 
WM_VKEYTOITEM Sent by a list box with the 


LBS_WANTKEYBOARDINPUT 
style to its owner in response to a 
WM_CHAR message. 


WM_VSCROLL Sent when the user clicks the vertical 
scroll bar with the mouse. 


5.4 System Messages 


System messages are sent by Windows to an application when a user accesses a 
window’s System menu, scroll bars, or size box. Although an application can 
process these messages, most applications pass them on to the DefWindowProc 
function for default processing. The following list briefly describes each system 


message: 

Message .. Description 

WM_SYSCHAR Results when a WM_SYSKEYUP 
j anda WM_SYSKEYDOWN 

message are translated. 
WM_SYSCOMMAND Sent when the user selects a com- 
‘ mand from the System menu. 
WM_SYSDEADCHAR Results when a WM_SYSKEYUP 


anda WM_SYSKEYDOWN 
message are translated. 


WM_SYSKEYDOWN Sent when the user holds down the 
ALT key and then presses another key. 


Message 


WM_SYSKEYUP 


5.5 Clipboard Messages 
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Description 


Sent when the user releases a key that 
was pressed while the ALT key was 
held down. 


Clipboard messages are sent by Windows to an application when other applica- 
tions try to access a window’s clipboard. The following list briefly describes 


each clipboard message: 


Message 


WM_ASKCBFORMATNAME 
WM_CHANGECBCHAIN 
WM_DESTROYCLIPBOARD 


WM_DRAWCLIPBOARD 


WM_HSCROLLCLIPBOARD 
WM_PAINTCLIPBOARD 


WM_RENDERALLFORMATS 
WM_RENDERFORMAT 
WM_SIZECLIPBOARD 


WM_VSCROLLCLIPBOARD 


Description 


Requests the name of the 
CF_OWNERDISPLAY format. 


Notifies viewing-chain members of a 
change in the chain. 


Signals that the contents of the clip- 
board are being destroyed. 


Signals an application to notify the 
next application in the chain of a clip- 
board change. - 


Requests horizontal scrolling for the 
CF_OWNERDISPLAY format. 


Requests painting of the 
CF_OWNERDISPLAY format. 


Notifies the clipboard owner that it 
must render the clipboard data in all 
possible formats. 


Notifies the clipboard owner that it 
must format the last data copied to 
the clipboard. 


Notifies the clipboard owner that the 
clipboard application’s window size 
has changed. 


Requests vertical scrolling for the 
CF_OWNERDISPLAY format. 
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5.6 System-Information Messages 


System-information messages are sent by Windows when an application or a 
user makes a system-wide change that affects other applications. The following 
list briefly describes each system-information message: 


Message 


WM_COMPACTING 


WM_DEVMODECHANGE 


WM_FONTCHANGE 
WM_PALETTECHANGED 


WM_SPOOLERSTATUS 
WM_SYSCOLORCHANGE 
WM_TIMECHANGE 


WM_WININICHANGE 


5.7 Control Messages 


Description 


Sent to all top-level windows when 
Windows requires too much system 
time compacting memory, indicating 
that system memory is low. 


Sent to all top-level windows when 
the user changes device-mode set- 
tings. 


Sent when the pool of font resources 
changes. 


Notifies all windows that the system 
color palette has changed. 


Sent from Print Manager whenever a 
job is added to or removed from the 
Print Manager queue. 


Sent to all top-level windows when a 
change is made in the system color 
setting. 


Sent when an application makes a 
change or set of changes to the sys- 
tem time. 


Sent when the Windows initialization 
file, WIN.INI, changes. 


Control messages are predefined window messages that direct a control to carry 
out a specified task. Applications send control messages to a control by using the 
SendMessage function. The control carries out the specified task and returns a 


value that indicates the result. 


The following messages apply to all controls: 
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Message Description 
WM_NEXTDLGCTL Sent to a dialog box’s window func- 
tion, to alter the control focus. 
WM_GETFONT Retrieves the current font used by a 
control for drawing text. 
WM_SETFONT Changes the font used by a control 


for drawing text. 


Sections 5.7.1 through 5.7.5 briefly describe the control messages for each con- 
trol class. 


5.7.1 Button-Control Messages 


Button-control messages are sent by an application to a button control. The fol- 
lowing list briefly describes each button-control message: 


Message Description 

BM_GETCHECK Determines whether a radio button or 
check box is checked. 

BM_GETSTATE Returns nonzero if the cursor is over 


the button and the user presses the 
mouse button or the SPACEBAR. 


BM_SETCHECK Checks or removes the checkmark 
from a radio button or check box. 
BM_SETSTATE Highlights a button or check box. 
BM_SETSTYLE Alters the style of a button. 
DM_GETDEFID Retrieves the ID of the default push- 
button control for a dialog box. 
DM_SETDEFID Changes the default push-button 


control ID for a dialog box. 


5.7.2 Edit-Control Messages 


Edit-control messages are sent by an application to an edit control. In addition to 
the messages described below, the WM_ENABLE, WM_GETTEXT, 
WM_GETTEXTLENGTH, WM_KILLFOCUS, WM_SETFOCUS, 
WM_SETREDRAW, and WM_SETTEXT window messages can be used. The 
following list briefly describes each edit-control message: 
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Message 


EM_CANUNDO 


EM_EMPTYUNDOBUFFER 


EM_FMTLINES 
EM_GETHANDLE 


EM_GETLINE 
EM_GETLINECOUNT 


EM_GETMODIFY 


EM_GETRECT 


EM_GETSEL 


EM_LIMITTEXT 


EM_LINEFROMCHAR 


EM_LINEINDEX 


EM_LINELENGTH 


EM_LINESCROLL 


Description 


Determines whether or not an edit 
control can respond correctly to an 
EM_UNDO message. 


Disables an edit control’s ability to 
undo the last edit. 


Directs the edit control to add or re- 
move the end-of-line character from 
wordwrapped text lines. 


Returns the data handle of the buffer 
used to hold the contents of the con- 
trol window. 


Copies a line from the edit control. 


Returns the number of lines of text in 
the edit control. 


Returns the current value of the mod- 
ify flag for a given edit control. The 
flag is set by the control if the user 
enters or modifies text within the con- 
trol. 


Returns the formatting rectangle of 
the edit control. 


Returns the starting and ending 
character positions of the current 
selection. 


Limits the length of the text (in 
bytes) the user may enter. 


Returns the line number of the line 
that contains the character whose 
position (indexed from the beginning 
of the text) is specified by the 
wParam parameter. 


Returns the number of character posi- 
tions that occur before the first 
character in a given line. 


Returns the length of a line (in bytes) 
in the edit control’s text buffer. 


Scrolls the contents of the edit con- 
trol by the given number of lines. 


Message 


EM_REPLACESEL 


EM_SETHANDLE 


EM_SETMODIFY 


EM_SETPASSWORDCHAR 


EM_SETRECT 
EM_SETRECTNP 


EM_SETSEL 


EM_SETTABSTOPS 


EM_SETWORDBREAK 


EM_UNDO 
WM_CLEAR 
WM_COPY 


WM_CUT 


WM_PASTE 


WM_UNDO 
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Description 


Replaces the current selection with 
new text. 


Establishes the text buffer used to 
hold the contents of the edit-control 
window. 


Sets the modify flag for a given edit 
control. 


Changes the password character for 
an edit control created with the 
ES_PASSWORD styles. 


Sets the formatting rectangle for an 
edit control. 


Identical to EM_SETRECT, except 
that the control is not repainted. 


Selects all characters in the current 
text that are within the starting and 
ending character positions given by 
the /Param parameter. 


Sets tab-stop positions in a multiline 
edit control. 


Informs a multiline edit control that 
Windows has replaced the default 
word-break function with an appli- 
cation-supplied word-break function. 


Undoes the last edit in an edit control. 
Deletes the current selection. 


Sends the current selection to the clip- 
board in CF_TEXT format. 


Sends the current selection to the clip- 
board in CF_TEXT format, and then 
deletes the selection from the control 
window. 


Inserts the data from the clipboard 
into the control window at the current 
cursor position. 


Undoes the previous action. 
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5.7.3 List-Box Messages 


List-box messages are sent by an application to a list box. The following list 
briefly describes each list-box message: 


Message Description 
LB_ADDSTRING Adds a string to the list box. 
LB_DELETESTRING Deletes a string from the list box. 
LB_DIR Adds a list of the files from the cur- 
. rent directory to the list box. 
LB_FINDSTRING Finds the first string in the list box 
which matches prefix text. 
LB_GETCOUNT Returns a count of the number of 
items in the list box. 
LB_GETCURSEL Returns the index of the currently 
selected item, if any. 
LB_GETHORIZONTALEXTENT Retrieves the width by which a list 
box can be scrolled horizontally. 
LB_GETITEMDATA Retrieves a 32-bit value associated 
with an item in an owner-draw list 
box. 
LB_GETITEMRECT Retrieves the coordinates of the 
, rectangle that bounds a list-box item. 
LB_GETSEL Returns the selection state of an item. 
LB_GETSELCOUNT Returns the total number of selected 
items in a multiselection list box. 
LB_GETSELITEMS Retrieves the indexes of the selected 
items in a multiselection list box. 
LB_GETTEXT Copies a string from the list box into 
a buffer. 
LB_GETTEXTLEN Returns the length of a string in the 
list box. 
LB_GETTOPINDEX Returns the index of the first visible 


item in a list box. 


LB_INSERTSTRING Inserts a string in the list box. 


Message 


LB_RESETCONTENT 


LB_SELECTSTRING 


LB_SELITEMRANGE 
LB_SETCOLUMNWIDTH 
LB_SETCURSEL 
LB_SETHORIZONTALEXTENT 
LB_SETITEMDATA 


LB_SETSEL 
LB_SETTABSTOPS 
LB_SETTOPINDEX 


5.7.4 Combo-Box Messages 
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Description 


Removes all strings from a list box 
and frees any memory allocated for 
those strings. 


Changes the current selection to the 
first string that has the specified pre- 
fix. 


Selects one or more consecutive 
items in a multiple-selection list box. 


Sets the width in pixels of all 
columns in a multicolumn list box. 


Selects a string and scrolls it into 
view, if necessary. 


Sets the width by which a list box can 
be scrolled horizontally. 


Sets a 32-bit value associated with an 
item in an owner-draw list box. 


Sets the selection state of a string. 
Sets tab-stop positions in a list box. 


Sets the first visible item in a list box 
to the item identified by an index. 


Combo-box messages are sent by an application to a combo box. The following 
list briefly describes each combo-box message: 


Message 


CB_ADDSTRING 
CB_DELETESTRING 
CB_DIR 


CB_FINDSTRING 


Description 


Adds a string to the list box of a 
combo box. 


Deletes a string from the list box of a 
combo box. 


Adds a list of the files from the cur- 
rent directory to the combo box. 


Finds the first string in the combo- | 
box list box which matches a prefix. 
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Message 


CB_GETCOUNT 
CB_GETCURSEL 


CB_GETEDITSEL . 


CB_GETITEMDATA 


CB_GETLBTEXT 
CB_GETLBTEXTLEN 


CB_INSERTSTRING 
CB_LIMITTEXT 


-CB_RESETCONTENT 


CB_SELECTSTRING 


CB_SETCURSEL 


CB_SETEDITSEL 


CB_SETITEMDATA 


CB_SHOWDROPDOWN 


Description 


Returns a count of the number of 
items in the combo box. 


Returns the index of the currently 
selected item, if any. 


Returns the starting and ending posi- 
tions of the selected text in the edit 
control of a combo box. 


Retrieves a 32-bit value associated 
with an item in an owner-draw 
combo box. 


Copies a string from the list box of a 
combo box into a buffer. 


Returns the length of a string in the 
list box of a combo box. 


Inserts a string in the combo box. 


Limits the length of the text that the 
user may enter into the edit control of 
a combo box. 


Removes all strings from a combo 
box and frees any memory allocated 
for those strings. 


Changes the current selection to the 
first string that has the specified pre- 
fix. The text in the edit control is 
changed to reflect the new selection. 


Selects a string and scrolls it into 
view, if necessary. 


Selects all characters in the edit con- 
tro] that are within specified starting 
and ending positions. 


Sets a 32-bit value associated with an 
item in an owner-draw combo box. 


Shows or hides a drop-down list box 
in a combo box. 
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5.7.5 Owner Dra w—-Control Messages 


Owner draw-control messages notify the owner of a control created with the 
OWNERDRAW style that the control needs to be drawn and to provide informa- . 
tion about the drawing required. The following list briefly describes these mes- 
sages: 


Message Description 


WM_COMPAREITEM Determines which of two items sorts above the other 
in a sorted owner-draw list box or combo box. 


WM_DELETEITEM Indicates that an item in an owner-draw list box or 
combo box has been deleted. 

WM_DRAWITEM Indicates that an owner-draw control needs to be red- 
rawn. 


WM_MEASUREITEM Requests the dimensions of an owner-draw combo 
box, list box, or menu item. 


5.8 Notification Messages 


Notification messages notify a control’s parent window of actions that occur 
within a control. Sections 5.8.1 through 5.8.4 briefly describe the notification 
messages for each notification class. 


Controls use the WM_COMMAND message to notify the parent window of ac- 
tions that occur within the control. The wParam parameter of the WM_COM- 
MAND message contains the control ID; the low-order word of the /Param 
parameter contains the control-window handle; and the high-order word of 
lParam contains the control notification code. 


5.8.1 Button Notification Codes 


The following notification codes apply to buttons: 


Message Description 
BN_CLICKED Indicates that the button has been clicked. 


BN_DOUBLECLICKED Indicates that the user has double-clicked an owner- 
draw or radio button. 
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5.8.2 Edit-Control Notification Codes 


The following notification codes apply to edit controls: 


Message 


EN_CHANGE 
EN_ERRSPACE 
EN_HSCROLL 
EN_KILLFOCUS 
EN_MAXTEXT 
EN_SETFOCUS 
EN_UPDATE 


EN_VSCROLL 


5.8.3 List-Box Notification Codes 


Description 


Indicates that the user has taken some action that 
may have changed the content of the text. 


Indicates that the edit control is out of space. 


Indicates that the user has clicked the edit control’s 
horizontal scroll bar with the mouse; the parent 
window is notified before the screen is updated. 


Indicates that the edit control has lost the input 
focus. 


Specifies that the current insertion has exceeded a 
specified number of characters for the edit control. 


Indicates that the edit control has obtained the input 
focus. 


' Specifies that the edit control will display altered 


text. 


Indicates that the user has clicked the edit control’s 
vertical scroll bar with the mouse; the parent 
window is notified before the screen is updated. 


The following notification codes apply only to list-box controls that have 


LBS_NOTIFY style: 


Message 


LBN_DBLCLK 


LBN_ERRSPACE 
LBN_KILLFOCUS 
LBN_SELCHANGE 
LBN_SETFOCUS 


Description 


Sent when the user double-clicks a string with the 
mouse. 


Sent when the system is out of memory. 
Indicates that a list box has lost input focus. 
Sent when the selection has been changed. 


Indicates that the list box has received input focus. 
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5.8.4 Combo-Box Notification Codes 


The following notification codes apply to combo boxes: 


Message | Description 

CBN_DBLCLK Sent when the user double-clicks a string with the 
mouse. 

CBN_DROPDOWN Informs the owner of the combo box that its list box 


is about to be dropped down. 


CBN_EDITCHANGE Indicates that the user has altered text in the edit con- 


trol. 
CBN_EDITUPDATE Indicates that the edit control will display altered 
text. 
CBN_ERRSPACE Sent when the system is out of memory. 
CBN_KILLFOCUS Indicates that a combo box has lost input focus. 
CBN_SELCHANGE Sent when the selection has been changed. 
CBN_SETFOCUS ee that the combo box has received input 
ocus. 


5.9 Scroll-Bar Messages 


There are two messages in the scroll-bar group: WM_HSCROLL and 
WM_VSCROLL. Scroll-bar controls send these messages to their parent 
windows whenever the user clicks in the control. The wParam parameter con- 
tains the same values as those defined for the scrolling messages of a standard 
window. The high-order word of the /Param parameter contains the window 
handle of the scroll-bar control. 


5.10 Nonclient-Area Messages 


Nonclient-area messages are sent by Windows to create and maintain the non- 
client area of an application’s window. Normally, applications do not process 
these messages, but send them on to the DefWindowProc function for pro- 
cessing. The following list briefly describes each nonclient-area message: 
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Message 


WM_NCACTIVATE 


WM_NCCALCSIZE 


WM_NCCREATE 


WM_NCDESTROY 


WM_NCHITTEST 


WM_NCLBUTTONDBLCLK 
Dees UTTONDOWN 
WM_NCLBUTTONUP 
WM_NCMBUTTONDBLCLK 
WM_NCMBUTTONDOWN 


WM_NCMBUTTONUP 


Description 


Sent to a window when its caption 
bar or icon needs to be changed to in- 
dicate an active or inactive state. 


Sent when the size of a window’s 
client area needs to be calculated. 


Sent prior to the WM_CREATE 
message when a window is first 
created. 


‘Sent after the WM_DESTROY 


message. 


Sent to the window that contains the 
cursor (unless a window has captured 
the mouse). 


Sent to a window when the left 
mouse button is double-clicked while 
the cursor is in a nonclient area of the 
window. 


Sent to a window when the left 
mouse button is pressed while the 
cursor is in a nonclient area of the 
window. 


Sent to a window when the left 
mouse button is released while the 
cursor is in a nonclient area of the 
window. 


Sent to a window when the middle 
mouse button is double-clicked while 
the cursor is in a nonclient area of the 
window. 


Sent to a window when the middle 
mouse button is pressed while the 
cursor is in a nonclient area of the 
window. 


Sent to a window when the left 
mouse button is released while the 
cursor is in a nonclient area of the 
window. 
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Message 


WM_NCMOUSEMOVE 


WM_NCPAINT 


WM_NCRBUTTONDBLCLK 


WM_NCRBUTTONDOWN 


WM_NCRBUTTONUP 


Description 


Sent to a window when the cursor is 
moved in a nonclient area of the 
window. 


Sent to a window when its border 
needs painting. 


Sent to a window when the right 
mouse button is double-clicked while 
the cursor is in a nonclient area of the 
window. 


Sent to a window when the right 
mouse button is pressed while the 
cursor is in a nonclient area of the 
window. 


Sent to a window when the right 
mouse button is released while the 
cursor is in a nonclient area of the 
window. 


5.77 Multiple Document Interface Messages 


Windows multiple document interface (MDI) provides applications with a stand- 
ard interface for displaying multiple documents within the same instance of an 
application. An MDI application creates a frame window which contains a client 
window in place of its client area. The application creates an MDI client window 
by calling CreateWindow with the MDICLIENT class and passing a CLIENT- 
CREATESTRUCT data structure as the function’s /pParam parameter. This 
client window in turn can own multiple child windows, each of which displays a 
separate document. An MDI application controls these child windows by sending 
messages to its client window. The following briefly describes these MDI mes- 


sages: 


Message 
WM_MDIACTIVATE 
WM_MDICASCADE 


WM_MDICREATE 
WM_MDIDESTROY 
WM_MDIGETACTIVE 


Description 
Activates a child window. 


Arranges child windows in a cascade 
format. 


Creates a child window. 
Closes a child window. 


Returns the current active MDI child 
window. 
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Message Description 

WM_MDIICONARRANGE Arranges all minimized child 
windows. 

WM_MDIMAXIMIZE Maximizes an MDI child window. 

WM_MDINEXT Activates the next child window. 

WM_MDIRESTORE Restores a child window from a maxi- 
mized or minimized state. 

WM_MDISETMENU Replaces the menu of an MDI frame 
window, the Window pop-up menu, 
or both. 

WM_MDITILE Arranges all child windows in a tiled 
format. 


5.12 Summary 


Windows messages provide the means of communication between the Windows 
system and applications, as well as among applications, in a nonpreemptive multi- 
tasking environment. For more information on topics related to Windows mes- 
sages, see the following: 


Topic Reference 

Message-processing Reference, Volume 1: Chapter 1, “Window 

functions Manager Interface Functions” 

Function descriptions Reference, Volume 1]: Chapter 4, “Functions 
Directory” 

Message descriptions Reference, Volume 1: Chapter 6, “Messages 
Directory” 

Windows data types and Reference, Volume 2: Chapter 7, “Data Types 

structures and Structures” 

Dynamic data exchange Reference, Volume 2: Chapter 15, “Windows 


DDE Protocol Definition” 


Guide to Programming: Chapter 22, “Dy- 
namic Data Exchange” 


General information on Guide to Programming: Chapter 1, “An 
Windows programming Overview of the Windows Environment” 
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Messages Directory 


Microsoft Windows communicates with applications through formatted window 
messages. These messages are sent to an application’s window function for pro- 
cessing. 


Some messages return values that contain information about the success of the 
message or other data needed by an application. To obtain the return value, the 
application must call SendMessage to send the message to a window. This func- 
tion does not return until the message has been processed. If the application does 
not require the return value of the message, it may call PostMessage to send the 
message. This function places a message in a window’s application queue and 
then returns immediately. If a message does not have a return value, then the 
application may use either function to send the message, unless indicated other- 
wise in the message description. 


A message consists of three parts: a message number, a word parameter, and a 
long parameter. Message numbers are identified by predefined message names. 
The message names begin with letters that suggest the meaning or origin of the 
message. The word and long parameters, named wParam and |Param respec- 
tively, contain values that depend on the message number. 


The /Param parameter often contains more than one type of information. For ex- 
ample, the high-order word may contain a handle to a window and the low-order 
word may contain an integer value. The HIWORD and LOWORD utility mac- 
ros can be used to extract the high- and low-order words of the /Param para- 
meter. The HIBYTE and LOBYTE utility macros can also be used with 
HIWORD and LOWORD to access any of the bytes. Casting can also be used. 


There are four ranges of message numbers, as shown in the following list: 


Range Meaning 

0 to WM_USER -— 1 Reserved for use by Windows. 

WM_USER to 0x7FFF Integer messages for use by applica- 
tions. 

0x8000 to OxBFFF Reserved for use by Windows. 

0xC000 to OxFFFF String messages for use by applica- 


tions. 
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Message numbers in the first range (0 to WM_USER -— 1) are defined by 
Windows. Values in this range that are not explicitly defined are reserved for fu- 
ture use by Windows. This chapter describes messages in this range. 


Message numbers in the second range (WM_USER to 7FFF) can be defined and 
used by an application to send messages within the application. These messages 
should not be sent to other applications unless the applications have been de- 
signed to exchange messages and to attach the same meaning to the message 
numbers. 


Message numbers in the third range (8000 to BFFF) are reserved for future use 
by Windows. 


Message numbers in the fourth range (C000 to FFFF) are defined at run time 
when an application calls the Register WindowMessage function to obtain a 
message number for a string. All applications that register the identical string can 
use the associated message number for exchanging messages with each other. 
The actual message number, however, is not a constant and cannot be assumed to 
be the same in different window sessions. 


This chapter lists messages in alphabetical order. For more information about 
messages, see Chapter 5, “Messages Overview.” 
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BM_GETCHECK 


Return Value 


BM_GETSTATE 


Return Value 


BM_SETCHECK 


This message determines whether a radio button or check box is checked. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 


The return value is nonzero if the radio button or check box is checked. Otherwise, it is 
zero. The BM_GETCHECK message always returns zero for a push button. 


This message determines the state of a button control when the user presses a mouse but- 
ton or the SPACEBAR. 


Parameter Description 
wParam Is not used. 


lParam Is not used. 


The BM_GETSTATE message returns a nonzero value if one of the following occurs: 


= A push button is highlighted. 
m The user presses a mouse button or the SPACEBAR when a button has the input focus. 


m= The user presses a mouse button when the cursor is over a button. 


Otherwise, BM_GETSTATE returns zero. 


This message checks or removes the checkmark from a radio button or check box. 


BM_SETSTATE 


Parameter 


wParam 


lParam 


Description 


Specifies whether to place or remove a checkmark inside the button 
or box. If the wParam parameter is nonzero, a checkmark is placed; 
if it is zero, the checkmark (if any) is removed. For three-state but- 
tons, if wParam is 1, a checkmark is placed beside the button. If 
wParam is 2, the button is grayed. If wParam is zero, the button is re- 
turned to its normal state (no checkmark or graying). 


Is not used. 


Comments The BM_SETCHECK message has no effect on push buttons. 


BM_SETSTATE 


This message displays a button or check box. 


Parameter Description 
wParam Specifies the highlighting action to be taken. If the wParam para- 
meter is nonzero, the button is highlighted (the interior is drawn 
using inverse video). If wParam is zero, the button is drawn in its reg- 
ular state. 
lParam Is not used. 
Comments Push buttons cannot be highlighted. 


BM_SETSTYLE 


This message alters the style of buttons. If the style contained in the wParam parameter 
differs from the existing style, the button is redrawn in the new style. 


Parameter 


wParam 


lParam 


Description 


Specifies the style value. For a complete description of possible but- 
ton styles, see Table 6.1, “Button Styles.” 


Specifies whether or not the buttons are to be redrawn. If [Param is 
zero, the buttons will not be redrawn. If /Param is nonzero, they will 
be redrawn. 


BM_SETSTYLE 


Comments 


Table 6.1 describes the available button styles: 


Table 6.1 Button Styles 


Value 


BS_AUTOCHECKBOX 


BS_AUTORADIOBUTTON 


BS_AUTO3STATE 


BS_CHECKBOX 


BS_DEFPUSHBUTTON 


BS_GROUPBOX 


BS_LEFTTEXT 


BS_OWNERDRAW 
BS_PUSHBUTTON 


BS_RADIOBUTTON 


BS_3STATE 


Meaning 


Identical to BS_CHECKBOXxX, except that the button au- 
tomatically toggles its state whenever the user clicks it. 


Identical to BS_RADIOBUTTON, except that the but- 
ton is checked, the application is notified by 
BN_CLICKED, and the checkmarks are removed from 
all other radio buttons in the group. 


Identical to BS_3STATE, except that the button auto- 
matically toggles its state when the user clicks it. 


Designates a box that may be checked; its border is bold 
when the user clicks the button. Any text appears to the 
right of the box. 


Designates a button with a bold border. This button rep- 
resents the default user response. Any text is displayed 
within the button. Windows sends a message to the 
parent window when the user clicks the button. 


Designates a rectangle into which other buttons are 
grouped. Any text is displayed in the rectangle’s upper- 
left corner. 


Causes text to appear on the left side of the radio button 
or check-box button. Use this style with the 
BS_CHECKBOX, BS_RADIOBUTTON, or 
BS_3STATE styles. 


Designates an owner-draw button. The parent window is 
notified when the button is clicked. Notification includes 
a request to paint, invert, and disable the button. 


Designates a button that contains the given text. The con- 
trol sends a message to its parent window whenever the 
user clicks the button. 


Designates a small circular button that can be checked; 
its border is bold when the user clicks the button. Any 
text appears to the right of the button. Typically, two or 
more radio buttons are grouped together to represent 
mutually exclusive choices, so no more than one button 
in the group is checked at any time. 


Identical to BS_CHECKBOX, except that the box can 
be grayed as well as checked. The grayed state typically 
is used to show that a check box has been disabled. 
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BN_CLICKED 
This code specifies that the user has clicked a button. The parent window receives the code 
through a WM_COMMAND message from a button control. 
Parameter Description 
wParam Specifies the control ID. 
lParam Contains a handle that identifies the button control in its low-order 
word and the BN_CLICKED notification code in its high-order 
word. 
Comments Disabled buttons will not send a BN_CLICKED notification message to a parent window. 


BN_DOUBLECLICKED 


This code specifies that the user has double-clicked a button. The control’s parent window 
receives this code through a WM_COMMAND message from a button control. 


Parameter Description 
wParam Specifies the control ID. 
lParam Contains a handle that identifies the button control in its low-order 
word and the BN_DOUBLECLICKED notification code in its high- 
order word. 
Comments This code applies to buttons with the BS_RADIOBUTTON and BS_OWNERDRAW 


styles only. 
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_ CB_ADDSTRIN 


Return Value 


Comments 


G [30] 


This message adds a string to the list box of a combo box. If the list box is not sorted, the 
string is added to the end of the list. If the list box is sorted, the string is inserted into the 
list after sorting. 


This message removes any existing list-box selections. 


Parameter Description 
wParam Is not used. 
lParam Points to the null-terminated string that is to be added. If the combo 


box was created with an owner-draw style but without the 
CBS_HASSTRINGS style, the /Param parameter is an application- 
supplied 32-bit value that is stored by the combo box instead of the 
pointer to the string. 


The return value is the index to the string in the list box. The return value is CB_ERR if an 
error occurs; the return value is CB_ERRSPACE if insufficient space is available to store 
the new string. 


If an owner-draw combo box was created with the CBS_SORT style but not the 
CBS_HASSTRINGS style, the WM_COMPAREITEM message is sent one or more times 
to the owner of the combo box so that the new item can be properly placed in the list box. 


CB_DELETESTRING 


Return Value 


Comments 


This message deletes a string from the list box. 


Parameter Description 
wParam Contains an index to the string that is to be deleted. 
lParam Is not used. 


The return value is a count of the strings remaining in the list. The return value is CB_ERR 
if wParam does not specify a valid index. 


If the combo box was created with an owner-draw style but without the CBS_HAS- 
STRINGS style, a WM_DELETEITEM message is sent to the owner of the combo box so 
the application can free additional data associated with the item (through the /Param para- 
meter of the CB_ADDSTRING or CB_INSERTSTRING message). 
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CB_DIR 


CB_DIR 


Return Value 


Comments 


This message adds a list of the files from the current directory to the list box. Only files 
with the attributes specified by the wParam parameter and that match the file specification 
given by the /Param parameter are added. 


Parameter Description 


wParam Contains a DOS attribute value. For a list of the DOS attributes, see 
the DlgDirList function in Chapter 4, “Functions Directory.” 


[Param Points to a file-specification string. The string can contain wildcard 
characters (for example, *.*). 


The return value is a count of items displayed. The return value is CB_ERR if an error oc- 
curs; the return value is CB_ERRSPACE if insufficient space is available to store the new 
strings. 


The return value of the CB_DIR message is one less than the return value of the CB_GET- 
COUNT message. 


CB_FINDSTRING 


Return Value 


Comments 


This message finds the first string in the list box of a combo box which matches the given 
prefix text. 


Parameter Description 


wParam Contains the index of the item before the first item to be searched. 
When the search reaches the bottom of the list box it continues from 
the top of the list box back to the item specified by wParam. If the 
wParam parameter is —1, the entire list box is searched from the 
beginning. 


lParam Points to the prefix string. The string must be null-terminated. 


The return value is the index of the matching item or CB_ERR if the search was unsuccess- 
ful. 


If the combo box was created with an owner-draw style but without the CBS_HAS- 
STRINGS style, this message returns the index of the item whose long value (supplied as 
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the /Param parameter of the CB_ADDSTRING or CB_LINSERTSTRING message) 
matches the value supplied as the /Param parameter of CB_FINDSTRING. 


CB_GETCOUNT 


This message returns a count of the items in a list box of a combo box. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 
Return Value The return value is a count of the items in the list box of a combo box. 


CB_GETCURSEL 


This message returns the index of the currently selected item, if any, in the list box of a 


combo box. 
Parameter Description 
wParam Is not used. 
lParam Is not used. 
Return Value The return value is the index of the currently selected item. It is CB_ERR if no item is 
selected. 


CB_GETEDITSEL 


This message returns the starting and ending positions of the selected text in the edit con- 
trol of a combo box. 


Parameter Description 
wParam Is not used. 


lParam Is not used. 
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CB_GETITEMDATA 


Return Value 


The return value is a long integer containing the starting position in the low-order word 
and the ending position in the high-order word. If this message is sent to a combo box 
without an edit control, the return value is CB_ERR. 


CB_GETITEMDATA 


Return Value 


This message retrieves the application-supplied 32-bit value associated with the specified 
combo-box item. If the item is in an owner-draw combo box created without the 
CBS_HASSTRINGS style, this 32-bit value was contained in the /Param parameter of the 
CB_ADDSTRING or CB_INSERTSTRING message that added the item to the combo 


box. Otherwise, it was the value in the /Param parameter of aCB_SETITEMDATA 
message. 


Parameter Description 
wParam Contains an index to the item. 
lParam Is not used. 


The return value is the 32-bit value associated with the item, or CB_ERR if an error occurs. 


CB_GETLBTEXT 


Return Value 


Comments 


This message copies a string from the list box of a combo box into a buffer. 


Parameter Description 
wParam Contains the index of the string to be copied. 
lParam Points to a buffer that is to receive the string. The buffer must have 


sufficient space for the string and a terminating null character. 


The return value is the length of the string in bytes, excluding the terminating null 
character. If wParam does not specify a valid index, the return value is CB_ERR. 


If the combo box was created with an owner-draw style but without the CBS_HAS- 
STRINGS style, the buffer pointed to by the /Param parameter of the message receives the 


32-bit value associated with the item through the /Param parameter of the CB_ADD- 
STRING or CB_LINSERTSTRING message. 
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CB_GETLBTEXTLEN 


Return Value 


This message returns the length of a string in the list box of a combo box. 


Parameter Description 
wParam Contains the index of the string. 
lParam Is not used. 


The return value is the length of the string in bytes, excluding the terminating null 
character. If wParam does not specify a valid index, the return value is CB_ERR. 


CB_INSERTSTRING 


Return Value 


This message inserts a string into the list box of a combo box. No sorting is performed. 


Parameter Description 


wParam Contains an index to the position that will receive the string. If the 
wParam parameter is —1, the string is added to the end of the list. 


lParam Points to the null-terminated string that is to be inserted. If the combo 
box was created with an owner-draw style but without the 
CBS_HASSTRINGS style, the /Param parameter is an application- 
supplied 32-bit value that is stored by the combo box instead of the 
pointer to the string. 


The return value is the index of the position at which the string was inserted. The return 
value is CB_ERR if an error occurs; the return value is CB_ERRSPACE if insufficient 
space is available to store the new string. 


CB_LIMITTEXT 


This message limits the length (in bytes) of the text that the user may enter into the edit 
control of a combo box. 
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Parameter Description 
wParam Specifies the maximum number of bytes which the user can enter. 
lParam Is not used. 

Return Value The return value is TRUE if the message is successful; otherwise, it is FALSE. If this 


message is sent to a combo box without an edit control, the return value is CB_ERR. 


CB_RESETCONTENT 


This message removes all strings from the list box of a combo box and frees any memory 
allocated for those strings. 


Parameter Description 
wParam Is not used. 
[Param Is not used. 
Comments If the combo box was created with an owner-draw style but without the CBS_HAS- 


STRINGS style, the owner of the combo box receives a WM_DELETEITEM message for 
each item in the combo box. 


CB_SELECTSTRING 


This message selects the first string in the list box of a combo box that matches the 
specified prefix. The text in the edit control of the combo box is changed to reflect the new 


selection. 

Parameter Description 

wParam Contains the index of the item before the first item to be searched. 
When the search reaches the bottom of the list box it continues from 
the top of the list box back to the item specified by wParam. If the 
wParam parameter is —1, the entire list box is searched from the 
beginning. 

lParam Points to the prefix string. The string must have a null-terminating 


character. 
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- Return Value 


: Comments 


The return value is the index of the newly selected item. If the search was unsuccessful, 
the return value is CB_ERR and the current selection is not changed. 


A string is selected only if its initial characters (from the starting point) match the 
characters in the prefix string. 


If the combo box was created with an owner-draw style but without the CBS_HAS- 
STRINGS style, this message returns the index of the item whose long value (supplied as 
the /Param parameter of the CB_ADDSTRING or CB_INSERTSTRING message) 
matches the value supplied as the /Param parameter of CB_FINDSTRING. 


CB_SETCURSEL 


Return Value 


This message selects a string in the list box of a combo box and scrolls it into view if the 
list box is visible, and the text in the combo-box edit control or static-text control is 
changed to reflect the new selection. When the new string is selected, the list box removes 
the highlight from the previously selected string. 


Parameter Description 


wParam Contains the index of the string that is to be selected. If wParam is 
—1, the list box is set to have no selection. 


lParam Is not used. 


If the index specified by wParam is not valid, the return value is CB_ERR and the current 
selection is not changed. 


CB_SETEDITSEL 


Return Value 


This message selects all characters in the edit control of a combo box that are within the 
starting and ending character positions specified by the /Param parameter. 


Parameter Description 
wParam Is not used. 
lParam Specifies the starting position in the low-order word and the ending 


position in the high-order word. 


The return value is TRUE if the message is successful; otherwise, it is FALSE. If this 
message is sent to a combo box without an edit control, the return value is CB_ERR. 
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CB_SETITEMDATA 


This message sets the 32-bit value associated with the specified item in a combo box. If 
the item is in an owner-draw combo box created without the CBS_HASSTRINGS style, 
this message replaces the 32-bit value that was contained in the /Param parameter of the 
CB_ADDSTRING or CB_INSERTSTRING message that added the item to the combo 


box. 

Parameter Description 

wParam Contains an index to the item. 

[Param Contains the new value to be associated with the item. 
Return Value The return value is CB_ERR if an error occurs. 


CB_SHOWDROPDOWN 


This message shows or hides the drop-down list box on a combo box created with the 
CBS_DROPDOWN or CBS_DROPDOWNLIST style. 
Parameter Description 


wParam If TRUE, displays the list box if it is not already visible. If FALSE, 


hides the list box if it is visible. 


lParam Not used. 


CBN_DBLCLK 


This code specifies that the user has double-clicked a string in the list box of a combo box. 


The control’s parent window receives this code through a WM_COMMAND message 
from the control. 


Parameter Description 
wParam Specifies the control ID of the combo box. 
lParam 


Contains the combo-box window handle in its low-order word and 
the CBN_DBLCLK code in its high-order word. 
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Comments This message can only occur for a combo box with a list box that is always visible. For 


combo boxes with drop-down list boxes, a single closes the list box and so a double-click 
cannot occur. 


CBN_DROPDOWN 


This code specifies that the list box of a combo box will be dropped down. It is sent just 
before the combo-box list box is made visible. The control’s parent window receives this 
code through a WM_COMMAND message from the control. 


Parameter Description 
wParam Specifies the control ID of the combo box. 
lParam Contains the combo-box window handle in its low-order word and 


the CBN_DROPDOWN code in the high-order word. 


Comments This message does not occur if the combo box does not contain a drop-down list box. 


CBN_EDITCHANGE 


This code indicates that the user has taken an action that may have altered the text in the 
edit control of a combo box. It is sent after Windows updates the display (unlike the 


CBN_EDITUPDATE code). The control’s parent window receives this code through a 
WM_COMMAND message from the control. 


Parameter Description 
wParam Specifies the control ID of the combo box. 
lParam Contains the combo-box window handle in its low-order word and 


the CBN_EDITCHANGE code in its high-order word. 


Comments This message does not occur if the combo box does not contain an edit control. 


CBN_EDITUPDATE 


This code specifies that a combo box containing an edit control will display altered text. 


The control’s parent window receives this code through a WM_COMMAND message 
from the control. 
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CBN_ERRSPACE 


Parameter Description 
wParam Specifies the control ID of the combo box. 
lParam Contains the combo-box window handle in its low-order word and 
the CBN_EDITUPDATE code in its high-order word. 
Comments This message does not occur if the combo box does not contain an edit control. 


CBN_ERRSPACE 


This code specifies that the combo-box list-box control cannot allocate enough memory to 


meet a specific request. The control’s parent window receives this code through a 
WM_COMMAND message from the control. 


Parameter 
wParam 


lParam 


CBN_KILLFOCUS 


Description 
Specifies the control ID of the combo box. 


Contains the combo-box window handle in its low-order word and 
the CBN_ERRSPACE code in its high-order word. 


This code is sent when a combo box loses input focus. The control’s parent window re- 
ceives this code through aWM_COMMAND message from the control. 


Parameter 
wParam 


lParam 


CBN_SELCHANGE 


Description 
Specifies the control ID of the combo box. 


Contains the combo-box window handle in its low-order word and 
the CBN_KILLFOCUS code in its high-order word. 


This code indicates that the selection in the list box of a combo box has changed either as a 
result of the user clicking in the list box or entering text in the edit control. The control’s 
parent window receives this code through aWM_COMMAND message from the control. 


CBN_SETFOCUS 
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Parameter Description 
wParam Specifies the control ID of the combo box. 
lParam Contains the combo-box window handle in its low-order word and 


the CBN_SELCHANGE code in its high-order word. 


CBN_SETFOCUS 


This code is sent when the combo box receives input focus. The control’s parent window 
receives this code through a WM_COMMAND message from the control. 


Parameter Description 
wParam Specifies the control ID of the combo box. 
lParam Contains the combo-box window handle in its low-order word and 


the CBN_SETFOCUS code in its high-order word. 
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DM_GETDEFID 


DM_GETDEFID 


Return Value 


DM_SETDEFID 


This message retrieves the ID of the default push-button control for a dialog box. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 


The return value is a 32-bit value. The high-order word contains DC_HASDEFID if the de- 
fault button exists; otherwise, it is NULL. The low-order word contains the ID of the de- 
fault button if the high-order word contains DC_HASDEFID; otherwise, it is zero. 


This message is used by an application to change the default push-button control ID for a 
dialog box. 
Parameter Description 


wParam Contains the ID of the new default push-button control. 


lParam Is not used. 


EM_CANUNDO | | 6-20 


EM_CANUNDO 
This message determines whether an edit control can respond correctly to an EM_UNDO 
message. 
Parameter Description 
wParam Is not used. 
[Param Is not used. 
Return Value The return value is nonzero if the edit control can process the EM_UNDO message cor- 


rectly. Otherwise, it is zero. 


EM_EMPTYUNDOBUFFER 


This message directs an edit control to clear its undo buffer. This disables the edit control’s 
ability to undo the last edit. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 
Comments The undo buffer is automatically emptied whenever the edit control receives a 


WM_SETTEXT or EM_SETHANDLE message. 


EM_FMTLINES 


This message directs a multiline edit control to add or remove the end-of-line character 
from word wrapped text lines. 


Parameter Description 


wParam Indicates the disposition of end-of-line characters. If the 
wParam parameter is nonzero, the characters CR CR LF 
(OD OD OA hexadecimal) are placed at the end of wordwrapped 
lines. If wParam is zero, the end-of-line characters are removed 
from the text. 


lParam Is not used. 
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Return Value The return value is nonzero if any formatting occurs. Otherwise, it is zero. 


Comments Lines that end with a hard return (a carriage return entered by the user) contain 
the characters CR LF at the end of the line. These lines are not affected by the 
EM_FMTLINES message. 


Notice that the size of the text changes when this message is processed. 


EM_GETHANDLE 


This message returns the data handle of the buffer that holds the contents of the control 
window. The handle is always a local handle to a location in the application’s data segment. 


Parameter Description 
wParam Is not used. 
[Param Is not used. 
Return Value The return value is a data handle that identifies the buffer that holds the contents of the edit 
control. 
Comments An application may send this message to a control only if it has created the dialog box con- ' 


taining the control with the DS_LOCALEDIT style flag set. 


EM_GETLINE | 

This message copies a line from the edit control. 

Parameter Description 

wParam Specifies the line number of the line in the control, where the 
line number of the first line is zero. 

[Param Points to the buffer where the line will be stored. The first word 
of the buffer specifies the maximum number of bytes to be 
copied to the buffer. The copied line is not null-terminated. 

Return Value The return value is the number of bytes actually copied. This message is not processed by 


single-line edit controls. 
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EM_GETLINECOUNT 


Return Value 


Comments 


This message returns the number of lines of text in the edit control. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 


The return value is the number of lines of text in the control. 


This message is not processed by single-line edit controls. 


EM_GETMODIFY 


Return Value 


EM_GETRECT 


This message returms the current value of the modify flag for a given edit control. The flag 
is set by the control if the user enters or modifies text within the control. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 


The return value is the value of the current modify flag for a given edit control. 


This message retrieves the formatting rectangle of the control. 


Parameter Description 
wParam : Is not used. 
IParam Points to a RECT data structure. The control copies the dimen- 


sions of the structure. 
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EM_GETSEL 
This message returns the starting and ending character positions of the current selection. 
Parameter Description 
wParam Is not used. 
lParam Is not used. 
Return Value The return value is a long value that contains the starting position in the low-order word. It 


contains the position of the first nonselected character after the end of the selection in the 
high-order word. 


EM_LIMITTEXT 


This message limits the length (in bytes) of the text the user may enter. 


Parameter Description 


wParam Specifies the maximum number of bytes that can be entered. If 
the user attempts to enter more characters, the edit control beeps 
and does not accept the characters. If the wParam parameter is 
zero, no limit is imposed on the size of the text (until no more 
memory is available). 


[Param Is not used. 


Comments The EM_LIMITTEXT message does not affect text set by the WM_SETTEXT message or 
the buffer set by the EM_SETHANDLE message. 


EM_LINEFROMCHAR 


This message returns the line number of the line that contains the character whose position 
(indexed from the beginning of the text) is specified by the wParam parameter. 
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Parameter Description 
wParam Contains the index value for the desired character in the text of 
the edit control (these index values are zero-based), or contains 
=, 
[Param . Is not used. 
Return Value The return value is a line number. If wParam is —1, the number of the line that contains the 


first character of the selection is returned; otherwise, wParam contains the index (or posi- 
tion) of the desired character in the edit-control text, and the number of the line that con- 
tains that character is returned. 


EM_LINEINDEX 


This message returns the number of character positions that occur preceding the first 
character in a given line. 


Parameter Description 


wParam Specifies the desired line number, where the line number of the 
first line is zero. If the wParam parameter is —1, the current line 
number (the line that contains the caret) is used. 


lParam Is not used. 

Return Value The return value is the number of character positions that precede the first character in the 
line. 

Comments This message will not be processed by single-line edit controls. 


EM_LINELENGTH 


This message returns the length of a line (in bytes) in the edit control’s text buffer. 
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Parameter Description 


wParam Specifies the character index of a character in the specified line, 
where the line number of the first line is zero. If the wParam 
parameter is —1, the length of the current line (the line that con- 
tains the caret) is returned, not including the length of any 
selected text. If the current selection spans more than one line, 
the total length of the lines, minus the length of the selected text, 


is returned. 
lParam Is not used. 
Comments Use the EM_LINEINDEX message to retrieve a character index for a given line number. 


This index can be used with the EM_LINELENGTH message. 


EM_LINESCROLL 


This message scrolls the content of the control by the given number of lines. 


Parameter Description 
wParam Is not used. 
[Param Contains the number of lines and character positions to scroll. 


The low-order word of the /Param parameter contains the num- 
ber of lines to scroll vertically; the high-order word contains the 
number of character positions to scroll horizontally. 


Comments This message will not be processed by single-line edit controls. 


EM_REPLACESEL 


This message replaces the current selection with new text. 


Parameter Description 
wParam Is not used. 


lParam Points to a null-terminated string of replacement text. 
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4 EM_SETHANDLE 
This message establishes the text buffer used to hold the contents of the control window. 


Parameter Description 


wParam Contains a handle to the buffer. The handle must be a local 
handle to a location in the application’s data segment. The edit 
control uses this buffer to store the currently displayed text, in- 
stead of allocating its own buffer. If necessary, the control 
reallocates this buffer. 


lParam Is not used. 


Comments This message will not be processed by single-line edit controls. 


If the EM_SETHANDLE message is used to change the text buffer used by an edit con- 
trol, the previous text buffer is not destroyed. The application must retrieve the previous 
buffer handle before setting the new handle, and must free-the old handle by using the 
LocalFree function. 


An edit control automatically reallocates the given buffer whenever it needs additional 
space for text, or it removes enough text so that additional space is no longer needed. An 
application may send this message to a control only if it has created the dialog box contain- 
ing the control with the DS_LOCALEDIT style flag set. 


EM_SETMODIFY 


This message sets the modify flag for a given edit control. 


Parameter Description 
wParam Specifies the new value for the modify flag. 
lParam Is not used. 


EM_SETPASSWORDCHAR 


This message sets the character displayed in an edit control created with the ES_PASS- 
WORD style. The default display character is an asterisk (*). 
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Parameter Description 


wParam Specifies the character to be displayed in place of the character 
typed by the user. If wParam is NULL, the actual characters 


typed by the user are displayed. 


lParam Is not used. 


EM_SETRECT 
This message sets the formatting rectangle for a control. The text is reformatted and redis- 
played to reflect the changed rectangle. 
Parameter Description 
wParam Is not used. 
lParam Points to a RECT data structure that specifies the new dimen- 
sions of the rectangle. 
Comments 


This message will not be processed by single-line edit controls. 


EM_SETRECTNP 


This message sets the formatting rectangle for a control. The text is reformatted and redis- 
played to reflect the changed rectangle. The EM_SETRECTNP message is the same as the 
EM_SETRECT message, except that the control is not repainted. Any subsequent altera- 
tions cause the control to be repainted to reflect the changed formatting rectangle. This 
message is used when the field is to be repainted later. 


Parameter Description 
wParam Is not used. 
lParam 


Points to a RECT data structure that specifies the new dimen- 
sions of the rectangle. 


Comments This message will not be processed by single-line edit controls. 
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EM_SETSEL 
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This message selects all characters in the current text that are within the starting and 
ending character positions given by the /Param parameter. 


Parameter Description 
wParam Is not used. 
lParam Specifies the starting position in the low-order word and the 


ending position in the high-order word. The position values 0 to 
32,767 select the entire string. 


EM_SETTABSTOPS 


Return Value 


Comments 


This message sets the tab-stop positions in a multiline edit control. 


Parameter Description 

wParam Is an integer that specifies the number of tab stops in the edit 
control. 

lParam Is a long pointer to the first member of an array of integers con- 


taining the tab stop positions in dialog units. (A dialog unit is a 
horizontal or vertical distance. One horizontal dialog unit is 
equal to 4 of the current dialog base width unit. The dialog base 
units are computed based on the height and width of the current 
system font. The GetDialogBaseUnits function returns the cur- 
rent dialog base units in pixels.) The tab stops must be sorted in 
increasing order; back tabs are not allowed. 


The return value is TRUE if all the tabs were set. Otherwise, the return value is FALSE. 


If wParam is zero and /Param is NULL, the default tab stops are set at every 32 dialog 
units. : 


If wParam is 1, the edit control will have tab stops separated by the distance specified by 
[Param. 


If [Param points to more than a single value, then a tab stop will be set for each value in 
[Param, up to the number specified by wParam. 
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EM_SETWORDBREAK 


EM_SETWORDBREAK 


Comments 


Callback Function 


This message is sent to the multiline edit control, informing the edit control that Windows 
has replaced the default word-break function with an application-supplied word-break 
function. A word-break function scans a text buffer (which contains text to be sent to the 
display), looking for the first word that will not fit on the current display line. The word- 
break function places this word at the beginning of the next line on the display. A word- 
break function defines at what point Windows should break a line of text for multiline edit 
controls, usually at a blank character that separates two words. The default word-break 
function breaks a line of text at a blank character. The application-supplied function may 
define a word break to be a hyphen or character other than the blank character. 


Parameter Description 
wParam Is not used. 
[Param Is a procedure-instance address. 


The callback-function address, passed as the /Param parameter, must be created by using 
the MakeProclInstance function. 


The callback function must use the Pascal calling convention and must be declared FAR. 


LPSTR FAR PASCAL WordBreakFunc(lpchEditText, ichCurrentWord, cchEditText) 
LPSTR [pchEditText; 

short ichCurrentWord; 

short cchEditText; 


WordBreakFunc is a placeholder for the application-supplied function name. The actual 
name must be exported by including it in an EXPORTS statement in the application’s 
module-definition file. 


Parameter Description 

IpchEditText Points to the text of the edit control. 

ichCurrentWord Specifies an index to a word in the buffer of text that identifies 
at what point the function should begin checking for a word 
break. 


cchEditText Specifies the number of bytes of edit text. 
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Return Value 


The return value points to the first byte of the next word in the edit-control text. If the cur- 
rent word is the last word in the text, the return value points to the first byte that follows 
the last word. 


EM_UNDO 
This message undoes the last edit to the edit control. When the user modifies the edit con- 
trol, the last change is stored in an undo buffer, which grows dynamically as required. If in- 
sufficient space is available for the buffer, the undo attempt fails and the edit control is 
unchanged. 
Parameter Description 
wParam Is not used. 
lParam Is not used. 

Return Value The return value is nonzero if the undo operation is successful. It is zero if the undo opera- 
tion fails. 

EN_CHANGE 


This code specifies that the user has taken an action that may have altered text. It is sent 
after Windows updates a display (unlike the EN_UPDATE code). The control’s parent 
window receives this code through a WM_COMMAND message from the control. 


Parameter Description 


wParam Contains the wParam parameter of the WM_COMMAND 
message, and specifies the control ID. 


lParam ; Contains an edit-control window handle in its low-order word 
and the EN_CHANGE code in its high-order word. 


EN_ERRSPACE 


This code specifies that the edit control cannot allocate additional memory space. The con- 


trol’s parent window receives this code through a WM_COMMAND message from the 
control. 
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Parameter Description 


wParam Contains the wParam parameter of the WM_COMMAND 
message, and specifies the control ID. 


lParam Contains an edit-control window handle in its low-order word 
and the EN_ERRSPACE code in its high-order word. 


EN_HSCROLL 


This code specifies that the user has clicked the edit control’s horizontal scroll bar. The 
control’s parent window receives this code through a WM_COMMAND message from the 
control. The parent window is notified before the screen is updated. 


Parameter Description 


wParam Contains the wParam parameter of the WM_COMMAND 
message, and specifies the control ID. 


lParam Contains an edit-control window handle in its low-order word 
and the EN_HSCROLL code in its high-order word. 


EN_KILLFOCUS 


This code specifies that the edit control has lost the input focus. The control’s parent 
window receives this code through a WM_COMMAND message from the control. 


Parameter Description 


wParam Contains the wParam parameter of the WM_COMMAND 
message, and specifies the control ID. 


lParam Contains an edit-control window handle in its low-order word 
and the EN_KILLFOCUS code in its high-order word. 


EN_MAXTEXT 


This code specifies that the current insertion has exceeded the specified number of 
characters for the edit control. The insertion has been truncated. This message is also sent 
when an edit control does not have the ES_ AUTOHSCROLL style and the number of 
characters to be inserted would exceed the width of the edit control. The control’s parent 
window receives this code through a WM_COMMAND message from the control. 


EN_SETFOCUS 


= 


EN_SETFOCUS 


EN_UPDATE 


Parameter 


wParam 


lParam 
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Description 


Contains the wParam parameter of the WM_COMMAND 
message, and specifies the control ID. 


Contains an edit-control window handle in its low-order word 
and the EN_MAXTEXT code in its high-order word. 


This code specifies that the edit control has obtained the input focus. The control’s parent 
window receives this code through a WM_COMMAND message from the control. 


Parameter 


wParam 


lParam 


Description 


Contains the wParam parameter of the WM_COMMAND | 
message, and specifies the control ID. 


Contains an edit-control window handle in its low-order word 
and the EN_SETFOCUS code in its high-order word. 


The code specifies that the edit control will display altered text. The control’s parent 
window receives this code through a WM_COMMAND message from the control; notifi- 
cation occurs after the control has formatted the text, but before it displays the text. This 
makes it possible to alter the window size, if necessary. 


Parameter 
wParam 


lParam 


Description 
Specifies the control ID. 


Contains an edit-control window handle in its low-order word 
and the EN_UPDATE code in its high-order word. 
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EN_VSCROLL 


EN_VSCROLL 


This code specifies that the user has clicked the edit control’s vertical scroll bar. The con- 
trol’s parent window receives this code through a WM_COMMAND message from the 
control; notification occurs before the screen is updated. 


Parameter Description 


wParam Contains the wParam parameter of the WM_COMMAND 
message, and specifies the control ID. 


lParam Contains an edit-control window handle in its low-order word 
and the EN_VSCROLL code in its high-order word. 
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Return Value 


Comments 


LB_ADDSTRING 


This message adds a string to the list box. If the list box is not sorted, the string is added to 
the end of the list. If the list box is sorted, the string is inserted into the list after sorting. 


This message removes any existing list-box selections. 


Parameter Description 
wParam Is not used. 
lParam Points to the null-terminated string that is to be added. If the list 


box was created with an owner-draw style but without the 
LBS_HASSTRINGS style, the /Param parameter is an 
application-supplied 32-bit value that is stored by the list 
box instead of the pointer to the string. . 


The return value is the index to the string in the list box. The return value is LB_ERR if an 
error occurs; the return value is LB_ERRSPACE if insufficient space is available to store 
the new string. 


If an owner-draw list box was created with the LBS_SORT style but not the LBS_HAS- 
STRINGS style, the WM_COMPAREITEM message is sent one or more times to the 
owner of the list box so the new item can be properly placed in the list box. 


LB_DELETESTRING 


Return Value 


Comments 


This message deletes a string from the list box. 


Parameter Description 
wParam Contains an index to the string that is to be deleted. 
lParam Is not used. 


The return value is a count of the strings remaining in the list. The return value is LB_ERR 
if an error occurs. 


If the list box was created with an owner-draw style but without the LBS_HASSTRINGS 
style, a WM_DELETEITEM message is sent to the owner of the list box so the application 
can free additional data associated with the item (through the /Param parameter of the 
LB_ADDSTRING or LB_INSERTSTRING message). 
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LB_DIR 


Return Value 


Comments 


This message adds a list of the files from the current directory to the list box. Only files 
with the attributes specified by the wParam parameter and that match the file specification 
given by the /Param parameter are added. 


Parameter Description 


wParam Contains a DOS attribute value. For a list of the DOS attributes, 
see the DlgDirList function in Chapter 4, “Functions Directory.” 


[Param Points to a file-specification string. The string can contain wild- 
card characters (for example, *.*). 


The return value is a count of items displayed. The return value is LB_ERR if an error oc- 
curs; the return value is LB_ERRSPACE if insufficient space is available to store the new 
strings. 


The return value of the LB_DIR message is one less than the return value of the LB_GET- 
COUNT message. 


LB_ FINDSTRING 


Return Value 


Comments 


This message finds the first string in the list box which matches the given prefix text. 


Parameter Description 


wParam Contains the index of the item before the first item to be 
searched. When the search reaches the bottom of the list box it 
continues from the top of the list box back to the item specified 
by wParam. If the wParam parameter is —1, the entire list box is 
searched from the beginning. 


lParam Points to the prefix string. The string must be null-terminated. 


The return value is the index of the matching item or LB_ERR if the search was unsuccess- 
ful. 


If the list box was created with an owner-draw style but without the LBS_HASSTRINGS 

style, this message returns the index of the item whose long value (supplied as the /Param 
parameter of the LB_ADDSTRING or LB_INSERTSTRING message) matches the value 
supplied as the /Param parameter of LB_FINDSTRING. 
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This message returns a count of the items in the list box. 


Parameter Description 
wParam Is not used. 
[Param Is not used. 


Return Value The return value is a count of the items in the list box. The return value is LB_ERR if an 
error occurs. 


LB_GETCURSEL 


This message returns the index of the currently selected item, if any. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 


Return Value The return value is the index of the currently selected item. It is LB_ERR if no item is 
selected or if the list-box type is multiple selection. 


LB_GETHORIZONTALEXTENT 


This message retrieves from a list box the width in pixels by which the list box can be 
scrolled horizontally if the list box has horizontal scroll bars. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 


Return Value The return value is the scrollable width of the list box, in pixels. 


Comments To respond to the LB_GETHORIZONTALEXTENT message, the list box must have been 
defined with the WS_HSCROLL style. 
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LB_GETITEMDATA 


LB_GETITEMDATA 


Return Value 


This message retrieves the application-supplied 32-bit value associated with the specified — 
list-box item. If the item is in an owner-draw list box created without the LBS_HAS- 
STRINGS style, this 32-bit value was contained in the /Param parameter of the LB_ADD- 
STRING or LB_INSERTSTRING message that added the item to the list box. Otherwise, 
it was the value in the /Param parameter of a LB_SETITEMDATA message. 


Parameter Description 
wParam Contains an index to the item. 
lParam Is not used. 


The return value is the 32-bit value associated with the item, or LB_ERR if an error occurs. 


LB_GETITEMRECT 


Return Value 


LB_GETSEL 


This message retrieves the dimensions of the rectangle that bounds a list-box item as it is 
currently displayed in the list-box window. 


Parameter Description 
wParam Contains an index to the item. 
lParam Contains a long pointer to a RECT data structure that receives 


the list-box client coordinates of the item. 


The return value is LB_ERR if an error occurs. 


This message returns the selection state of an item. 


Parameter Description 


wParam Contains an index to the item. 


[Param Is not used. 


re 
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LB_GETSELCOUNT 


Return Value 


Return Value 
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The return value is a positive number if an item is selected. Otherwise, it is zero. The re- 
turn value is LB_ERR if an error occurs. 


LB_GETSELCOUNT 


This message returns the total number of selected items in a multiselection list box. 


Parameter Description 
wParam Not used. 
[Param Not used. 


The return value is the count of selected items in a list box. If the list box is a single-selec- 
tion list box, the return value is LB_ERR. 


LB_GETSELITEMS 


Return Value 


LB_GETTEXT 


This message fills a buffer with an array of integers specifying the item numbers of 
selected items in a multiselection list box. 
Parameter Description 


wParam Specifies the maximum number of selected items whose item 


numbers are to be placed in the buffer. 


lParam Contains a long pointer to a buffer large enough for the number 


of integers specified by the wParam parameter. 


The return value is the actual number of items placed in the buffer. If the list box is a 
single-selection list box, the return value is LB_ERR. 


This message copies a string from the list into a buffer. 


Parameter Description 


wParam Contains the index of the string to be copied. 
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Parameter Description 
lParam Points to the buffer that is to receive the string. The buffer must 
have both sufficient space for the string and a terminating null 
character. 
Return Value The return value is the length of the string (in bytes), excluding the terminating null 


character. The return value is LB_ERR if the wParam parameter is not a valid index. 


Comments If the list box was created with an owner-draw style but without the LBS_HASSTRINGS 
style, the buffer pointed to by the /Param parameter of the message receives the 32-bit 
value associated with the item through the /Param parameter of the LB_ADDSTRING or 
LB_INSERTSTRING message. 


LB_GETTEXTLEN 


This message returns the length of a string in the list box. 


Parameter Description 
wParam Contains an index to the string. 
lParam Is not used. 
Return Value The return value is the length of the string (in bytes), excluding the terminating null 


character. The return value is LB_ERR if an error occurs. 


LB_GETTOPINDEX 


This message returns the index of the first visible item in a list box. Initially, item 0 is at 
the top of the list box, but if the list box is scrolled, another item may be at the top. 


Parameter Description 
wParam Not used. 
[Param Not used. 


Return Value The index of the first visible item in a list box. 


1 
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LB_INSERTSTRING 


Return Value 


This message inserts a string into the list box. No sorting is performed. 


Parameter Description 

wParam Contains an index to the position that will receive the string. If 
the wParam parameter is —1, the string is added to the end of the 
list. 

lParam Points to the null-terminated string that is to be inserted. If the 


list box was created with an owner-draw style but without the 
LBS_HASSTRINGS style, the /Param parameter is an appli- 
cation-supplied 32-bit value that is stored by the list box instead 
of the pointer to the string. 


The return value is the index of the position at which the string was inserted. The return 
value is LB_ERR if an error occurs; the return value is LB_ERRSPACE if insufficient 
space is available to store the new string. 


LB_RESETCONTENT 


Comments 


This message removes all strings from a list box and frees any memory allocated for those 
strings. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 


If the list box was created with an owner-draw style but without the LBS_HASSTRINGS 
style, the owner of the list box receives a WM_DELETEITEM message for each item in 
the list box. 


LB_SELECTSTRING 


This message changes the current selection to the first string that has the specified prefix. 
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Parameter Description 


wParam Contains the index of the item before the first item to be 
searched. When the search reaches the bottom of the list box it 
continues from the top of the list box back to the item specified 
by wParam. If the wParam parameter is —1, the entire list box is 
searched from the beginning. 


lParam Points to the prefix string. The string must have a null-terminat- 
ing character. 


Return Value The return value is the index of the selected item. The return value is LB_ERR if an error 
occurs. 
Comments This message must not be used with list boxes that are multiple-selection type. 


A String is selected only if its initial characters (from the starting point) match the 
characters in the prefix string. 


x 


If the list box was created with an owner-draw style but without the LBS_HASSTRINGS 
style, this message retums the index of the item whose long value (supplied as the /Param 
parameter of the LB_ADDSTRING or LB_INSERTSTRING message) matches the value 
supplied as the /Param parameter of LB_FINDSTRING. 


LB_SELITEMRANGE 


This message selects one or more consecutive items in a multiple-selection list box. 


Parameter Description 


wParam Specifies how to set the selection. If the wParam parameter is 
nonzero, the string is selected and highlighted; if wParam is 
zero, the highlight is removed and the string is no longer 
selected. 


lParam The low-order word of the /Param parameter is an index that 
specifies the first item to set, and the high-order word is an 
index that specifies the last item to set. 


Return Value The return value is LB_ERR if an error occurs. 


Comments This message should be used only with multiple-selection list boxes. 


LB SETCOLUMNWIDTH 6-42 


LB_SETCOLUMNWIDTH | 


This message is sent to a multicolumn list box created with the LBS_MULTICOLUMN 
style to set the width in pixels of all columns in the list box. 


Parameter Description 
wParam Specifies the width in pixels of all columns. 
lParam Is not used, 


LB_SETCURSEL 


This message selects a string and scrolls it into view, if necessary. When the new string is 
selected, the list box removes the highlight from the previously selected string. 


Parameter Description 
wParam Contains the index of the string that is selected. If wParam is -1, 
the list box is set to have no selection. 
lParam Is not used. 
Return Value The return value is LB_ERR if an error occurs. 


Comments This message should be used only with single-selection list boxes. It cannot be used to set 


or remove a selection in a multiple-selection list box. 


LB_SETHORIZONTALEXTENT 


. This message sets the width in pixels by which a list box can be scrolled horizontally. If 
the size of the list box is smaller than this value, the horizontal scroll bar will horizontally 


scroll items in the list box. If the list box is as large or larger than this value, the horizontal 
scroll bar is disabled. 


Parameter Description 
wParam Specifies the number of pixels by which the list box can be 
scrolled. 


lParam Is not used. 
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LB_SETITEMDATA 


Comments 


To respond to the LB_SETHORIZONTALEXTENT message, the list box must have been 
defined with the WS_HSCROLL style. 


LB_SETITEMDATA 


This message sets a 32-bit value associated with the specified item in a list box. If the item 
is in an owner-draw list box created without the LBS_HASSTRINGS style, this message 
replaces the 32-bit value that was contained in the /Param parameter of the LB_ADD- 
STRING or LB_INSERTSTRING message that added the item to the list box. 


Return Value 


LB_SETSEL 


Return Value 


Comments 


Parameter 


wParam 


[Param 


Description 
Contains an index to the item. 


Contains the new value to be associated with the item. 


The return value is LB_ERR if an error occurs. 


This message selects a string in a multiple-selection list box. 


Parameter 


wParam 


[Param 


Description 


Specifies how to set the selection. If the wParam parameter is 
nonzero, the string is selected and highlighted; if wParam is 
zero, the highlight is removed and the string is no longer 
selected. 


The low-order word of the /Param parameter is an index that 
specifies which string to set. If /Param is —-1, the selection is 
added to or removed from all strings, depending on the value of 
wParam. 


The return value is LB_ERR if an error occurs. 


This message should be used only with multiple-selection list boxes. 


LB SETTABSTOPS 6-44 


i LB_SETTABSTOPS 


Return Value 


Comments 


This message sets the tab-stop positions in a list box. 


Parameter Description 

wParam Is an integer that specifies the number of tab stops in the list 
box. 

lParam Is a long pointer to the first member of an array of integers con- 


taining the tab stop positions in dialog units. (A dialog unit is a 
horizontal or vertical distance. One horizontal dialog unit is 
equal to 4 of the the current dialog base width unit. The dialog 
base units are computed based on the height and width of the 
current system font. The GetDialogBaseUnits function returns 
the current dialog base units in pixels.) The tab stops must be 
sorted in increasing order; back tabs are not allowed. 


The return value is TRUE if all the tabs were set. Otherwise, the return value is FALSE. 


If wParam is zero and [Param is NULL, the default tab stop is two dialog units. 


If wParam is 1, the edit control will have tab stops separated by the distance specified by 
[Param. 


If [Param points to more than a single value, then a tab stop will be set for each value in 
[Param, up to the number specified by wParam. 


To respond to the LB_SETTABSTOPS message, the list box must have been created with 
the LBS_USETABSTOPS style. 


LB_SETTOPINDEX 


Return Value 


This message sets the first visible item in a list box to the item identified by the index. 


Parameter Description 
wParam Specifies the index of the list-box item. 
lParam Not used. 


The return value is LB_ERR if an error occurs. 
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LBN_DBLCLK 


This code specifies that the user has double-clicked a string. The control’s parent window 
receives this code through a WM_COMMAND message from the control. 


Parameter Description 


wParam Contains the wParam parameter of the 


WM_COMMAND message, and specifies the control ID. 
lParam Contains an edit-control window handle in its low-order word 
and the LBN_DBLCLK code in its high-order word. 


Comments This code applies only to list-box controls that have LBS_NOTIFY style. 


LBN_ERRSPACE 


This code specifies that the list-box control cannot allocate enough memory to meet a 


specific request. The control’s parent window receives this code through a WM_COM- 
MAND message from the control. 


Parameter Description 


wParam Contains the wParam parameter of the WM_COMMAND 
message, and specifies the control ID. 

lParam Contains a list-box window handle in its low-order word and the 
LBN_ERRSPACE code in its high-order word. 


Comments This code applies only to list-box controls that have LBS_NOTIFY style. 


LBN_KILLFOCUS 


This code is sent when a list box loses input focus. The control’s parent window receives 
this code through a WM_COMMAND message from the control. 


Parameter Description 
wParam — Specifies the control ID of the list box. 
lParam 


Contains the list-box window handle in its low-order word and the 
LBN_KILLFOCUS code in its high-order word. 
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§ 


4 LBN_SELCHANGE 
pa 


This code specifies that the selection in a list box has changed. The control’s parent 
window receives this code through a WM_COMMAND message from the control. 


Parameter _ Description 


wParam Contains the wParam parameter of the WM_COMMAND 
message, and specifies the control ID. 
lParam Contains a list-box window handle in its low-order word and the 


LBN_SELCHANGE code in its high-order word. 


Comments This code applies only to list-box controls that have LBS_NOTIFY style. 


LBN_SETFOCUS 


This code is sent when the list box receives input focus. The control’s parent window re- 
ceives this code through a WM_COMMAND message from the control. 


Parameter Description 
wParam Specifies the control ID of the list box. 
lParam 


Contains the list-box window handle in its low-order word and the 
LBN_SETFOCUS code in its high-order word. 
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WM_ACTIVATE 


This message is sent when a window becomes active or inactive. 


Parameter Description 


wParam Specifies the new state of the window. The wParam parameter is 
zero if the window is inactive; it is one of the following nonzero 
values if the window is being activated: 


Value Meaning 


The window is being activated through some 
method other than a mouse click (for example, 
through a call to the SetActiveWindow function or 
selection of the window by the user through the key- 
board interface). 


p The window is being activated by a mouse click by 
the user. Any mouse button can be clicked: right, 
left, or middle. 


lParam Identifies a window and specifies its state. The high-order word of 
the /Param parameter is nonzero if the window is minimized. 
Otherwise, it is zero. The value of the low-order word of /Param 
depends on the value of the wParam parameter. If wParam is 
zero, the low-order word of /Param is a handle to the window 
being activated. If wParam is nonzero, the low-order word of 
lParam is the handle of the window being inactivated (this handle 
may be NULL). 


Default Action If the window is being activated and is not minimized, the DefWindowProc function sets 
the input focus to the window. 


WM_ACTIVATEAPP 


This message is sent when a window being activated belongs to a different application 
than the currently active window. The message is sent to the application whose window 
will be activated and the application whose window will be deactivated. 
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Parameter Description 


wParam Specifies whether a window is being activated or deactivated. A 
nonzero value indicates that Windows will activate a window; 
zero indicates that Windows will deactivate a window. 


> lParam Contains the task handle of the application. If the wParam para- 
meter is zero, the low-order word of the /Param parameter 
contains the task handle of the application that owns the window 
that is being deactivated. If wParam is nonzero, the low-order 
word of /Param contains the task handle of the application that 


owns the window that is being activated. The high-order word is 
not used. 


WM_ASKCBFORMATNAME 


This message is sent when the clipboard contains a data handle for the CF_OWNER- 
DISPLAY format (that is, the clipboard owner should display the clipboard contents), and 
requests a copy of the format name. 


Parameter Description 
wParam Specifies the maximum number of bytes to copy. 
lParam Points to the buffer where the copy of the format name is to be 
stored. . 
Comments The clipboard owner should copy the name of the CF_OWNERDISPLAY format into the 


specified buffer, not exceeding the maximum number of bytes. 


WM_CANCELMODE 
This message cancels any mode the system is in, such as one that tracks the mouse in a 


scroll bar or moves a window. Windows sends the WM_CANCELMODE message when 
an application displays a message box. 


Parameter Description 
wParam Is not used. 


[Param Is not used. 
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WM_CHANGECBCHAIN 


WM_CHANGECBCHAIN 


This message notifies the first window in the clipboard-viewer chain that a window is 


Commenis 


WM_CHAR 


being removed from the chain. 


Parameter Description 


wParam Contains the handle to the window that is being removed from 
the clipboard-viewer chain. 


lParam Contains in its low-order word the handle to the window that fol- 
lows the window being removed from the clipboard-viewer 


chain. 


Each window that receives the WM_CHANGECBCHAIN message should call the Send- 
Message function to pass on the message to the next window in the clipboard-viewer 
chain. If the window being removed is the next window in the chain, the window specified 
by the low-order word of the /Param parameter becomes the next window, and clipboard 


messages are passed on to it. 


This message results when a WM_KEYUP and a WM_KEYDOWN message are trans- 
lated. It contains the value of the keyboard key being pressed or released. 


Parameter Description 
wParam Contains the value of the key. 
lParam Contains the repeat count, scan code, key-transition code, pre- 


vious key state, and context code, as shown in the following list: 


Bit 


0-15 (low-order 
word) 


16-23 (low byte 
of high-order 
word) 


24 


Value 


Repeat count (the number of times the 
key stroke is repeated as a result of the 
user holding down the key). 


Scan code (OEM-dependent value). 


Extended key, such as a function key ora 
key on the numeric keypad (1 if it is an 
extended key). 


vy 
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Comments 


Parameter Description 

Bit Value 

25-26 Not used. 

27-28 © Used internally by Windows. 

29 Context code (1 if the ALT key is held 

. down while the key is pressed, 0 other- 
wise). 

30 Previous key state (1 if the key is down 
before the message is sent, 0 if the key is 
up). 

31 Transition state (1 if the key is being 


released, 0 if the key is being pressed). 


Since there is not necessarily a one-to-one correspondence between keys pressed and 
character messages generated, the information in the high-order word of the /Param para- 
meter is generally not useful to applications. The information in the high-order word ap- 
plies only to the most recent WM_KEYUP or WM_KEYDOWN message that precedes 
the posting of the character message. 


For IBM® Enhanced 101- and 102-key keyboards, enhanced keys are the right ALT and the 
right CONTROL keys on the main section of the keyboard; the INSERT, DELETE, HOME, END, 
PAGE UP, PAGE DOWN and DIRECTION keys in the clusters to the left of the numeric key 
pad; and the divide (/) and ENTER keys in the numeric key pad. Some other keyboards may 
support the extended-key bit in the /Param parameter. 


WM_CHARTOITEM 


This message is sent by a list box with the LBS_WANTKEYBOARDINPUT style to its 
owner in response to a WM_CHAR message. 


Parameter Description 
wParam Contains the value of the key which the user pressed. 
lParam Contains the current caret position in its high-order word and the 


window handle of the list box in its low-order word. 
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Return Value 


The return value specifies the action which the application performed in response to the 
message. A return value of —2 indicates that the application handled all apsects of selecting 
the item and wants no further action by the list box. A return value of —1 indicates that the 
list box should perform the default action in response to the key stroke. A return value of 
zero or greater specifies the index of an item in the list box and indicates that the list box 
should perform the default action for the key stroke on the given item. 


WM_CHILDACTIVATE 


This message is sent to a child window’s parent window when the SetWindowPos func- 
tion moves a child window. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 


WM_CLEAR 
This message deletes the current selection. 
Parameter Description 
wParam Is not used. 
lParam Is not used. 
WM_CLOSE 
This message occurs when a window is closed. 
Parameter ‘ Description 
wParam Is not used. 
lParam Is not used. 
Default Action 


The DefWindowProc function calls the DestroyWindow function to destroy the window. 
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Comments 


, WM_COMMAN 


Comments 


An application can prompt the user for confirmation, prior to destroying a window, by pro- 
cessing the WM_CLOSE message and calling the DestroyWindow function only if the 
user confirms the choice. 


D 


This message occurs when the user selects an item from a menu, when a control passes a 
message to its parent window, or when an accelerator key stroke is translated. 


Parameter Description 
wParam Contains the menu item, the control ID, or the accelerator ID. 
lParam Specifies whether the message is from a menu, an accelerator, or 


a control. The low-order word contains zero if the message is 
from a menu. The high-order word contains 1 if the message is 
an accelerator message. If the message is from a control, the — 
high-order word of the /Param parameter contains the notifica- 
tion code. The low-order word is the window handle of the 
control sending the message. 


Accelerator key strokes that are defined to select items from the System menu are trans- 
lated into WM_SYSCOMMAND messages. 


If an accelerator key stroke that corresponds to a menu item occurs when the window that 
owns the menu is minimized, no WM_COMMAND message is sent. However, if an accel- 
erator key stroke that does not match any of the items on the window’s menu or on the Sys- 
tem menu occurs, a WM_COMMAND message is sent, even if the window is minimized. 


WM_COMPACTING 


This message is sent to all top-level windows when Windows detects that more than 12.5 
percent of system time over a 30- to 60-second interval is being spent compacting 
memory. This indicates that system memory is low. 


When an application receives this message, it should free as much memory as possible, 
taking into account the current level of activity of the application and the total number of 
applications running in Windows. The application can call the GetNumTasks function to 
determine how many applications are running. 
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WmM_COMPAREITEM 


Parameter Description 

wParam Specifies the ratio of CPU time currently spent by Windows 
compacting memory. For example, 8000h represents 50% of 
CPU time. 

lParam Is not used. 


WM_COMPAREITEM 


Return Value 


This message determines the relative position of a new item in a sorted owner-draw combo 
or list box. 


Whenever the application adds a new item, Windows sends this message to the owner of a 
combo or list box created with the CBS_SORT or LBS_SORT style. The /Param para- 
meter of the message is a long pointer to a COMPAREITEMSTRUCT data structure that 
contains the identifiers and application-supplied data for two items in the combo or list 
box. When the owner receives the message, the owner returns a value indicating which of 
the items should appear before the other. Typically, Windows sends this message several 
times until it determines the exact position for the new item. 


Parameter Description 
wParam Is not used. . 
lParam Contains a long pointer to a COMPAREITEMSTRUCT data 


structure that contains the identifiers and application-supplied 
data for two items in the combo or list box. 


The return value indicates the relative position of the two items. It may be any of the fol- 
lowing values: 


Value Meaning 
—1 Item 1 sorts before item 2. 
0 Item | and item 2 sort the same. 


1 Item 1 sorts after item 2. 


v¥ 
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WM_COPY 
This message sends the current selection to the clipboard in CF_TEXT format. 
Parameter Description 
wParam Is not used. 
lParam Is not used. 
WM_CREATE 


This message informs the window procedure that it can perform any initialization. The 
CreateWindow function sends this message before it returns and before the window is 


opened. 

Parameter Description 

wParam Is not used. 

lParam Points to a CREATESTRUCT data structure that contains cop- 


ies of parameters passed to the CreateWindow function. 


WM_CTLCOLOR 


This message is sent to the parent window of a predefined control or message box when 
the control or message box is about to be drawn. By responding to this message, the parent 
window can set the text and background colors of the child window by using the display- 
context handle given in the wParam parameter. 


Parameter Description 
wParam Contains a handle to the display context for the child window. 
lParam The low-order word of the /Param parameter contains the handle to 


the child window. The high-order word is one of the following 
values, specifying the type of control: 


Value Control Type 
CTLCOLOR_BTN Button control 
CTLCOLOR_DLG Dialog box 
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Farameter ——- Description 

Value Control Type 
CTLCOLOR_EDIT Edit control 
CTLCOLOR_LISTBOX List-box control 
CTLCOLOR_MSGBOX Message box 
CTLCOLOR_SCROLLBAR Scroll-bar control 
CTLCOLOR_STATIC Static control 

Default Action The DefWindowProc function selects the default system colors. 

Comments When processing the WM_CTLCOLOR message, the application must align the origin of 


the intended brush with the window coordinates by first calling the UnrealizeObject func- 
tion for the brush, and then setting the brush origin to the upper-left corner of the window. 


If an application processes the WM_CTLCOLOR message, it must return a handle to the 
brush that is to be used for painting the control background. Note that failure to return a 
valid brush handle will place the system in an unstable state. 


WM_CUT 


This message sends the current selection to the clipboard in CF_TEXT format, and then de- 
letes the selection from the control window. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 


WM_DEADCHAR 


This message results when a WM_KEYUP and a WM_KEYDOWN message are trans- 
lated. It specifies the character value of a dead key. A dead key is a key, such as the umlaut 
(double-dot) character, that is combined with other characters to form a composite 
character. For example, the umlaut-O character consists of the dead key, umlaut, and the O 
key. 


WO 


Wi_DEADCHAR 


Comments 
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Parameter Description 
wParam Contains the dead-key character value. 
lParam Contains the repeat count, scan code, key-transition code, pre- 


vious key state, and context code, as shown in the following list: 


Bit - Value 
0-15 (low-order Repeat count (the number of times the 
word) key stroke is repeated as a result of the 


user holding down the key). 


16-23 (low byte Scan code (OEM-dependent value). 

of high-order 

word) 

24 Extended key, such as a function key ora 


key on the numeric keypad (1 if it is an 
extended key, 0 otherwise). 


25-26 Not used. 

27-28 Used internally by Windows. 

29 Context code (1 if the ALT key is held 
down while the key is pressed, O other- 
wise). 

30 Previous key state (1 if the key is down 
before the message is sent, 0 if the key is 
up). 

31 Transition state (1 if the key is being 


released, 0 if the key is being pressed). 


The WM_DEADCHAR message typically is used by applications to give the user feed- 
back about each key pressed. For example, an application can display the accent in the cur- 
rent character position without moving the caret. 


Since there is not necessarily a one-to-one correspondence between keys pressed and 
character messages generated, the information in the high-order word of the /Param para- 
meter is generally not useful to applications. The information in the high-order word ap- 
plies only to the most recent WM_KEYUP or WM_KEYDOWN message that precedes 
the posting of the character message. 


For IBM Enhanced 101- and 102-key keyboards, enhanced keys are the right ALT and the 
right CONTROL keys on the main section of the keyboard; the INSERT, DELETE, HOME, END, 
PAGE UP, PAGE DOWN and DIRECTION keys in the clusters to the left of the numeric key 
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pad; and the divide (/) and ENTER keys in the numeric key pad. Some other keyboards may 
support the extended-key bit in the /Param parameter. 


WM_DELETEITEM 


This message informs the owner of an owner-draw list box or combo box that a list-box 
item has been removed. This message is sent when the list box or combo box is destroyed 
or the item is removed by the LB_DELETESTRING, LB_RESETCONTENT, 
CB_DELETESTRING or CB_RESETCONTENT message. 


Parameter | Description 

wParam Not used. 

lParam Contains a long pointer to a DELETEITEMSTRUCT data 
structure that contains information about the deleted list-box 
item. 


WM_DESTROY 


This message informs the window that it is being destroyed. The DestroyWindow func- 
tion sends the WM_DESTROY message to the window after removing the window from 
the screen. The WM_DESTROY message is sent to a parent window before any of its 
child windows are destroyed. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 
Comments If the window being destroyed is part of the clipboard-viewer chain (set by using the Set- 


Clipboard Viewer function), the window must remove itself from the clipboard viewer 


chain by processing the ChangeClipboardChain function before returning from the 
WM_DESTROY message. 


WM_DESTROYCLIPBOARD 


This message is sent to the clipboard owner when the clipboard is emptied through a call 
to the EmptyClipboard function. 


WM_DEVMODECHANGE 


6-58 
Parameter Description 
wParam Is not used. 
lParam Is not used. 
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_ WM_DEVMODECHANGE 


This message is sent to all top-level windows when the user changes device-mode settings. 


Parameter Description 

wParam Is not used. 

lParam Points to the device name specified in the Windows initialization 
file, WIN.INI. 


WM_DRAWCLIPBOARD 


This message is sent to the first window in the clipboard-viewer chain when the contents 
of the clipboard change. Only applications that have joined the clipboard-viewer chain by 
calling the SetClipboardViewer function need to process this message. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 
Comments Each window that receives the WM_DRAWCLIPBOARD message should call the Send- 


Message function to pass the message on to the next window in the clipboard-viewer 
chain. The handle of the next window is returned by the SetClipboard Viewer function; it 
may be modified in response to a WM_CHANGECBCHAIN message. 


WM_DRAWITEM 


This message informs the owner-draw button, combo box, list box, or menu that a visual 
aspect of the control has changed. The itemAction field in the DRAWITEMSTRUCT 
structure defines the drawing operation that is to be performed. The data in this field al- 
lows the control owner to determine what drawing action is required. 


6-59 WM_ENABLE 

Parameter Description 

wParam Is not used. 

[Param Contains a long pointer to a DRAWITEMSTRUCT data struc- 
ture that contains information about the item to be drawn and the 
type of drawing required. 

Comments Before returning from processing this message, an application should restore all objects 
selected for the display context supplied in the hDC field of the DRAWITEMSTRUCT 
data structure. 

WM_ENABLE 


This message is sent after a window has been enabled or disabled. 


Parameter Description 


wParam Specifies whether the window has been enabled or disabled. The 
wParam parameter is nonzero if the window has been enabled; 
it is zero if the window has been disabled. 


[Param Is not used. 


WM_ENDSESSION 


Comments 


This message is sent to tell an application that has responded nonzero to a WM_QUERY- 
ENDSESSION message whether the session is actually being ended. 


Parameter Description 


wParam Specifies whether or not the session is being ended. It is nonzero 
if the session is being ended. Otherwise, it is zero. 


lParam Is not used. 


If the wParam parameter is nonzero, Windows can terminate any time after all applica- 
tions have returned from processing this message. Consequently, an application should per- 
form all tasks required for termination before returning from this message. 


The application does not need to call the Destroy Window or PostQuitMessage function 
when the session is being ended. 
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WM_ENTERIDLE 


Default Action 


This message informs an application’s main windows procedure that a modal dialog box or 
a menu is entering an idle state. A modal dialog box or menu enters an idle state when no 
messages are waiting in its queue after it has processed one or more previous messages. 


Parameter Description 


wParam Specifies whether the message is the result of a dialog box or a menu 
being displayed. It is one of these values: 


Value Meaning 

MSGF_DIALOGBOX The system is idle because a 
dialog box is being displayed. 

MSGF_MENU The system is idle because a 


menu is being displayed. 


lParam Contains in its low-order word the handle of the dialog box (if 
wParam is MSGF_DIALOGBOX) or of the window containing the 
displayed menu (if wParam is MSGF_MENU). The high-order word 
is not used. 


The DefWindowProc function returns zero. 


WM_ERASEBKGND 


Return Value 


Default Action 


This message is sent when the window background needs erasing (for example, when a 
window is resized). It is sent to prepare an invalidated region for painting. 


Parameter Description 
wParam Contains the device-context handle. 
lParam Is not used. 


The return value is nonzero if the background is erased. Otherwise, it is zero. If the applica- 
tion processes the WM_ERASEBKGND message, it should return the appropriate value. 


The background is erased, using the class background brush specified by the hbrback- 
ground field in the class structure. . 
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WM_FONTCHANGE 


Comments 


If hbrbackground is NULL, the application should process the WM_ERASEBKGND 
message and erase the background color. When processing the WM_ERASEBKGND 
message, the application must align the origin of the intended brush with the window 


coordinates by first calling the UnrealizeObject function for the brush, and then selecting 
the brush. 


Windows assumes the background should be computed by using the MM_TEXT mapping 
mode. If the device context is using any other mapping mode, the area erased may not be 
within the visible part of the client area. 


WM_FONTCHANGE 


Comments 


This message occurs when the pool of font resources changes. Any application that adds or 
removes fonts from the system (for example, through the AddFontResource or Re- 
moveFontResource function) should send this message to all top-level windows. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 


To send the WM_FONTCHANGE message to all top-level windows, an application can 
call the SendMessage function with the hWnd parameter set to OXFFFF. 


WM_GETDLGCODE 


Return Value 


This message is sent by Windows to an input procedure associated with a control. Nor- 
mally, Windows handles all DIRECTION-key and TAB-key input to the control. By respond- 
ing to the WM_GETDLGCODE message, an application can take control of a particular 
type of input and process the input itself. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 


The return value is one or more of the following values, indicating which type of input the 
application processes: 
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Default Action 


Comments 


Value Meaning 
DLGC_DEFPUSHBUTTON Default push button. 
DLGC_HASSETSEL EM_SETSEL messages. 
DLGC_PUSHBUTTON Push button. 
DLGC_RADIOBUTTON Radio button. 
DLGC_WANTALLKEYS All keyboard input. 
DLGC_WANTARROWS DIRECTION keys. 
DLGC_WANTCHARS WM_CHAR messages. 
DLGC_WANTMESSAGE All keyboard input (the application 

passes this message on to control). 
DLGC_WANTTAB TAB key. 


The DefWindowProc function returns zero. 


Although the DefWindowProc function always returns zero in response to the » 
WM_GETDLGCODE message, the window functions for the predefined control classes 
return a code appropriate for each class. 


The WM_GETDLGCODE message and the returned values are useful only with user-de- 
fined dialog controls or standard controls modified by subclassing. 


WM_GETFONT 


Return Value 


This message retrieves from a control the font with which the control is currently drawing 
its text. 


Parameter Description 
wParam Not used. 
lParam Not used. 


The return value is the handle of the font used by the control, or NULL if it is using the sys- 
tem font. 
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WM_GETMINMAXINFO 


WM_GETMINMAXINFO 


This message is sent to a window whenever Windows needs to know the maximized size 
of the window, the minimum or maximum tracking size of the window, or the maximized 
position of the window. The maximized size of a window is the size of a window when its 
borders are fully extended. The maximum tracking size of a window is the largest window 
size that can be achieved by using the borders to size the window. The minimum tracking 
size of a window is the smallest window size that can be achieved by using-the borders to 


size the window. 


Parameter 
wParam 


[Param 


Description 
Is not used. 


Points to an array of five points that contains the following infor- 
mation: 


Point Description 
rgpt[0] Used internally by Windows. 
rgpt[1] The maximized size, which is the screen 


size by default. The width is 
(SM_CXSCREEN + (2 x 
SM_CXFRAME)). The height is 
(SM_CYSCREEN + (2 x SM_CY- 
FRAMEB)). 


rgpt[2] The maximized position of the upper-left 
comer of the window (in screen coordi- 
nates). The default x value is 
SM_CXFRAME. The default y value is 
SM_CYFRAME. 


rgpt[3] The minimum tracking size, which is the 
iconic size by default. The width is 
SM_CXMINTRACK. The height is 
SM_CYMINTRACK. 


rgept[4] _ The maximum tracking size, which is 
less than the screen size by default. The 
width is (SM_CXSCREEN + (2 x 
SM_CXFRAME)). The height ts 
(SM_CYSCREEN + (2 x SM_CY- 
FRAMEB)). 


> 
> 


WM_GETTEXT 
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Comments 


WM_GETTEXT 


Return Value 


The array contains default values for each point before Windows sends the WM_GET- 


MINMAXINFO message. This message gives the application the opportunity to alter the 
default values. 


This message is used to copy the text that corresponds to a window. For edit controls and 

combo-box edit controls, the text to be copied is the content of the edit control. For button 
controls, the text is the button name. For lixt boxes, the text is the currently selected item. 

For other windows, the text is the window caption. 


Parameter Description 


wParam Specifies the maximum number of bytes to be copied, including 
the null-terminating character. 


lParam Points to the buffer that is to receive the text. 


The return value is the number of bytes copied. It is LB_ERR if no item is selected or 
CB_ERR if the combo box has no edit control. 


WM_GETTEXTLENGTH 


Comments 


This message is used to find the length (in bytes) of the text associated with a window. The 
length does not include the null-terminating character. For edit controls and combo-box 
edit controls, the text is the content of the control. For lixt boxes, the text is the currently 


selected item. For button controls, the text is the button name. For other windows, the text 
is the window caption. 


Parameter Description 
wParam Is not used. 
[Param Is not used. 


The return value is the length of the given text. 


WM_HSCROLL 


6-65 
WM_HSCROLL 
This message is sent when the user clicks the horizontal scroll bar. 
Parameter Description 
wParam Contains a scroll-bar code that specifies the user’s scrolling request. 
It can be any one of the following values: 
Value Meaning 
SB_BOTTOM Scroll to lower right. 
SB_ENDSCROLL End scroll. 
SB_LINEDOWN Scroll one line down. 
SB_LINEUP Scroll one line up. 
SB_PAGEDOWN Scroll one page down. 
SB_PAGEUP Scroll one page up. 
SB_THUMBPOSITION Scroll to absolute position. The 
current position is provided in 
the low-order word of /Param. 
SB_THUMBTRACK Drag thumb to specified posi- 
tion. The current position is 
provided in the low-order word 
of /Param. 
SB_TOP Scroll to upper left. 
[Param Specifies the window handle of the control. If the message is sent by 
a scroll-bar control, the high-order word of the /Param parameter 
contains the window handle of the control. If the message is sent as a 
result of the user clicking a pop-up window’s scroll bar, the high- 
order word is not used. 
Comments The SB_THUMBTRACK message typically is used by applications that give some feed- 


back while the thumb is being dragged. 


If an application scrolls the document in the window, it must also reset the position of the 


thumb by using the SetScrollPos function. 
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WM_HSCROLLCLIPBOARD 


This message is sent when the clipboard contains a data handle for the CF_OWNERDIS- 
PLAY format (specifically the clipboard owner should display the clipboard contents) and 
an event occurs in the clipboard application’s horizontal scroll bar. 


Parameter Description 

wParam Contains a handle to the clipboard application window. 

lParam Contains one of the following scroll-bar codes in the low-order word: 
Value Meaning 
SB_BOTTOM Scroll to lower right. 
SB_ENDSCROLL End scroll. 
SB_LINEDOWN Scroll one line down. 
SB_LINEUP Scroll one line up. 
SB_PAGEDOWN Scroll one page down. 
SB_PAGEUP Scroll one page up. 
SB_THUMBPOSITION Scroll to absolute position. 
SB_TOP Scroll to upper left. 


The high-order word of the /Param parameter contains the thumb 
position if the scroll-bar code is SB_THUMBPOSITION. Otherwise, 
the high-order word is not used. 


Comments The clipboard owner should use the InvalidateRect function or repaint as desired. The 
scroll-bar position should also be reset. 


WM_ICONERASEBKGND 


This message is sent to a minimized (iconic) window when the background of the icon 
must be filled before painting the icon. A window receives this message only if a class icon 
is defined for the window. Otherwise, WM_ERASEBKGND is sent instead. Passing this 
message to the DefWindowProc function permits Windows to fill the icon background 
with the background brush of the parent window. 
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Parameter Description 
wParam Contains the device-context handle of the icon. 
[Param Is not used. 


WM_INITDIALOG 


This message is sent immediately before a dialog box is displayed. By processing this. 
message, an application can perform any initialization before the dialog box is made vis- 
ible. 


Parameter Description 


wParam Identifies the first control item in the dialog box that can be 
given the input focus. Generally, this is the first item in the 
dialog box with WS_TABSTOP style. 


lParam Is the value passed as the dw/nitParam parameter of the function 
if the dialog box was created by any of the following functions: 


a CreateDialogIndirectParam 
a CreateDialogParam 

= DialogBoxIndirectParam 

= DialogBoxParam 


Otherwise, /Param is not used. 


Comments If the application returns a nonzero value in response to the WM_INITDIALOG message, 
Windows sets the input focus to the item identified by the handle in the wParam para- 
meter. The application can return FALSE only if it has set the input focus to one of the con- 
trols of the dialog box. 


WM_INITMENU 


This message is a request to initialize a menu. It occurs when a user moves the mouse into 
a menu bar and clicks, or presses a menu key. Windows sends this message before display- 
ing the menu. This allows the application to change the state of menu items before the 
menu is shown. 


WM_INITMENUPOPUP 
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Parameter Description 
wParam Contains the menu handle of the menu that is to be initialized. 
lParam Is not used. 


Comments A WM_INITMENU message is sent only when a menu is first accessed; only one WM_IN- 


ITMENU message is generated for each access. This means, for example, that moving the 
mouse across several menu items while holding down the button does not generate new 
messages. This message does not provide information about menu items. 


WM_INITMENUPOPUP 


This message is sent immediately before a pop-up menu is displayed. Processing this 
message allows an application to change the state of items on the pop-up menu before the 
menu is shown, without changing the state of the entire menu. 


Parameter Description ; 
wParam Contains the menu handle of the pop-up menu. 
lParam Specifies the index of the pop-up menu. The low-order word 


contains the index of the pop-up menu in the main menu. The 
high-order word is nonzero if the pop-up menu is the system 
menu. Otherwise, it is zero. 


WM_KEYDOWN 


This message is sent when a nonsystem key is pressed. A nonsystem key is a keyboard key 


that is pressed when the ALT key is not Paested: or a keyboard key that is pressed when a 
window has the input focus. 


Parameter Description 
wParam Specifies the virtual-key code of the given key. 
lParam 


Contains the repeat count, scan code, key-transition code, pre- 
vious key state, and context code, as shown in the following list: 
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Parameter Description 

Bit Value 

0-15 (low-order Repeat count (the number of times the 

word) key stroke is repeated as a result of the 
user holding down the key). 

16-23 (low byte Scan code (OEM-dependent value). 

of high-order 

word) 

24 . Extended key, such as a function key or a 
key on the numeric key pad (1 if it is an 
extended key). 

25-26 Not used. 

27-28 Used internally by Windows. 

29 Context code (1 if the ALT key is held 
down while the key is pressed, 0 other- 
wise). 

30 Previous key state (1 if the key is down 
before the message is sent, 0 if the key is 
up). 

31 Transition state (1 if the key is being 


released, 0 if the key is being pressed). 


For WM_KEYDOWN messages, the key-transition bit (bit 31) 
is O and the context-code bit (bit 29) is 0. 


Comments Because of auto-repeat, more than one WM_KEYDOWN message may occur before a 
WM_KEYUP message is sent. The previous key state (bit 30) can be used to determine 
whether the WM_KEYDOWN message indicates the first down transition or a repeated 
down transition. 


For IBM Enhanced 101- and 102-key keyboards, enhanced keys are the right ALT and the 
right CONTROL keys on the main section of the keyboard; the INSERT, DELETE, HOME, END, 
PAGE UP, PAGE DOWN and DIRECTION keys in the clusters to the left of the numeric key 
pad; and the divide (/) and ENTER keys in the numeric key pad. Some other keyboards may 
support the extended-key bit in the /Param parameter. 
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WM_KEYUP 
This message is sent when a nonsystem key is released. A nonsystem key is a keyboard 
key that is pressed when the ALT key is not pressed, or a keyboard key that is pressed when 
a window has the input focus. 
Parameter Description 
wParam Specifies the virtual-key code of the given key. 
lParam Contains the repeat count, scan code, key-transition code, pre- 

vious key state, and context code, as shown in the following list: 

Bit Value 

0-15 (low-order Repeat count (the number of times the 

word) key stroke is repeated as a result of the 
user holding down the key). 

16-23 (low byte Scan code (OEM-dependent value). 

of high-order | 

word) 

24 Extended key, such as a function key or a 
key on the numeric key pad (1 if it is an 
extended key). 

25-26 Not used. 

27-28 Used internally by Windows. 

29 Context code (1 if the ALT key is held 
down while the key is pressed, 0 other- 
wise). 

30 Previous key state (1 if the key is down 
before the message is sent, 0 if the key is 
up). 

31 Transition state (1 if the key is being 
released, 0 if the key is being pressed). 

For WM_KEYUP messages, the key-transition bit (bit 31) is 1 

and the context-code bit (bit 29) is 0. 

Comments For IBM Enhanced 101- and 102-key keyboards, enhanced keys are the right ALT and the 


right CONTROL keys on the main section of the keyboard; the INSERT, DELETE, HOME, END, 
PAGE UP, PAGE DOWN and DIRECTION keys in the clusters to the left of the numeric key 
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pad; and the divide (/) and ENTER keys in the numeric key pad. Some other keyboards may 
support the extended-key bit in the /Param parameter. 


WM_KILLFOCUS 


This message is sent immediately before a window loses the input focus. 


Parameter : Description 
wParam Contains the handle of the window that receives the input focus 
(may be NULL). 
[Param Is not used. 
Comments If an application is displaying a caret, the caret should be destroyed at this point. 


WM_LBUTTONDBLCLK 


This message occurs when the user double-clicks the left mouse button. 


Parameter Description 


wParam Contains a value that indicates whether various virtual keys are 
down. It can be any combination of the following values: 


Value Meaning 

MK_CONTROL Set if CONTROL key is down. 
MK_LBUTTON Set if left button is down. 
MK_MBUTTON Set if middle button is down. 
MK_RBUTTON Set if right button is down. 
MK_SHIFT _ Set if SHIFT key is down. 


[Param Contains the x- and y-coordinates of the cursor. The x-coordinate 
is in the low-order word; the y-coordinate is in the high-order 
word. These coordinates are always relative to the upper-left 
corner of the window. 


Comments Only windows whose window class has CS_DBLCLKS style can receive double-click 
messages. Windows generates a double-click message when the user presses, releases, and 
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then presses a mouse button again within the system’s double-click time limit. Double- 
clicking actually generates four messages: a down-click message, an up-click message, the 
double-click message, and another up-click message. 


WM_LBUTTONDOWN 


This message occurs when the user presses the left mouse button. 


Parameter Description 


wParam Contains a value that indicates whether various virtual keys are 
down. It can be any combination of the following values: 


Value Meaning 
MK_CONTROL Set if CONTROL key is down. 
MK_MBUTTON Set if middle button is down. 
MK_RBUTTON Set if right button is down. 
MK_SHIFT Set if SHIFT key is down. 

lParam Contains the x- and y-coordinates of the cursor. The x-coordinate 


is in the low-order word; the y-coordinate is in the high-order 
word. These coordinates are always relative to the upper-left 


corner of the window. 


WM_LBUTTONUP 


This message occurs when the user releases the left mouse button. 


Parameter Description 


wParam Contains a value that indicates whether various virtual keys are 
down. It can be any combination of the following values: 


MK_CONTROL 
MK_MBUTTON 
MK_RBUTTON 


Meaning 
Set if CONTROL key is down. 
Set if middle button is down. 


Set if right button is down. 
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WM_MBUTTONDBLCLK 


Parameter 


lParam 


WM_MBUTTONDBLCLK 


This message occurs when the user double-clicks the middle mouse button. 


Comments 


Parameter 


wParam 


lParam 


Description 
Value Meaning 
MK_SHIFT Set if SHIFT key is down. 


Contains the x- and y-coordinates of the cursor. The x-coordinate 
is in the low-order word; the y-coordinate is in the high-order 
word. These coordinates are always relative to the upper-left 
corner of the window. 


Description 


Contains a value that indicates whether various virtual keys are 
down. It can be any combination of the following values: 


Value Meaning 


MK_CONTROL Set if CONTROL key is down. 
MK_LBUTTON Set if left button is down. 
MK_MBUTTON Set if middle button is down. 
MK_RBUTTON Set if right button is down. 
MK_SHIFT Set if SHIFT key is down. 


Contains the x- and y-coordinates of the cursor. The x-coordinate 
is in the low-order word; the y-coordinate is in the high-order 
word. These coordinates are always relative to the upper-left 
corer of the window. 


Only windows whose window class has CS_DBLCLKS style can receive double-click 
messages. Windows generates a double-click message when the user presses, releases, and 
then presses a mouse button again within the system’s double-click time limit. Double- 
clicking actually generates four messages: a down-click message, an up-click message, the 
double-click message, and another up-click message. 
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WM_MBUTTONDOWN 


This message occurs when the user presses the middle mouse button. 


Parameter Description 


wParam Contains a value that indicates whether various virtual keys are 
down. It can be any combination of the following values: 


Value’ Meaning 

MK_CONTROL Set if CONTROL key is down. 
MK_LBUTTON Set if left button is down. 
MK_RBUTTON Set if right button is down. 
MK_SHIFT Set if SHIFT key is down. 


lParam Contains the x- and y-coordinates of the cursor. The x-coordinate 
is in the low-order word; the y-coordinate is in the high-order 
word. These coordinates are always relative to the upper-left 
corner of the window. 


WM_MBUTTONUP 


This message occurs when the user releases the middle mouse button. 


Parameter Description 


wParam Contains a value that indicates whether various virtual keys are 
down. It can be any combination of the following values: 


Value Meaning 

MK_CONTROL Set if CONTROL key is down. 
MK_LBUTTON __ Setif left button is down. 
MK_RBUTTON Set if right button is down. 
MK_SHIFT Set if SHIFT key is down. 


[Param Contains the x- and y-coordinates of the cursor. The x-coordinate 
is in the low-order word; the y-coordinate is in the high-order 
word. These coordinates are always relative to the upper-left 
corner of the window. . 
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WM_MDIACTIVATE 


An application sends this message to a multiple document interface (MDI) client window 
to instruct the client window to activate a different MDI child window. As the client 
window processes this message, it sends WM_MDIACTIVATE to the child window being 
deactivated and to the child window being activated. 


Parameter Description 


wParam When the application sends the WM_MDIACTIVATE message’ 
to its MDI client window, the wParam parameter contains the 
window handle of the MDI child window to be activated. When 
the client window sends the message to a child window, 
wParam is TRUE if the child is being activated and FALSE if it 
is being deactivated. 


lParam When received by an MDI child window, the /Param parameter 

contains in its high-order word the window handle of the child 
window being deactivated and in its low-order word the window 
handle of the child window being activated. When this message 
is sent to the client window, /Param should be set to NULL. 


Comments MDI child windows are activated independently of the MDI frame window. When the 
frame becomes active, the child window that was last activated with the WM_MDIAC- 
TIVE message receives the WM_NCACTIVATE message to draw an active window frame 
and caption bar, but it does not receive another WM_MDIACTIVATE message. 


WM_MDICASCADE 


This message arranges the child windows of a multiple document interface (MDI) client 
window in a “cascade” format. 


Parameter Description 
wParam Not used. 
[Param Not used. 


WM_MDICREATE 


This message causes a multiple document interface (MDI) client window to create a child 
window. 


WM_MDIDESTROY oa 


Return Value 


Comments 


Parameter Description 

wParam Not used. 

lParam Contains a long pointer to an MDICREATESTRUCT data 
structure. 


The return value contains the identifier of the new window in the low word and zero in the 
high word. 


The window is created with the style bits WS_CHILD, WS_CLIPSIBLINGS, WS_CLIP- 


_ CHILDREN, WS_SYSMENU, WS_CAPTION, WS_THICKFRAME, WS_MINIMIZE- 


BOX, and WS_MAXIMIZEBOxX, plus additional style bits specified in the 
MDICREATESTRUCT data structure to which /Param points. Windows adds the title of 
the new child window to the window menu of the frame window. An application should 
create all child windows of the client window with this message. 


If a client window receives any message that changes the activation of child windows and 
the currently active MDI child window is maximized, Windows restores the currently ac- 
tive child and maximizes the newly activated child. 


When the MDI child window is created, Windows sends the WM_CREATE message to 
the window. The /Param parameter of the WM_CREATE message contains a pointer toa 
CREATESTRUCT data structure. The IpCreateParams field of the CREATESTRUCT 
structure contains a pointer to the MDICREATESTRUCT data structure passed with the 
WM_MDICREATE message that created the MDI child window. 


An application should not send a second WM_MDICREATE message while a 
WM_MDICREATE message is still being processed. For example, it should not send a 
WM_MDICREATE message while an MDI child window is processing its WM_CREATE 
message. 


WM_MDIDESTROY 


When sent to a multiple document interface (MDI) client window, this message causes a 
child window to be closed. 


Parameter Description 
wParam Contains the window handle of the child window. 


[Param Not used. 
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Comments This message removes the title of the child window from the frame window and deacti- 


vates the child window. An application should close all MDI child windows with this 
message. 


If a client window receives any message that changes the activation of child windows and 


the currently active MDI child window is maximized, Windows restores the currently ac- 
tive child and maximizes the newly activated child. 


WM_MDIGETACTIVE 


This message returns the current active multiple document interface (MDI) child window, 
along with a flag indicating whether the child is maximized or not. 


Parameter Description 
wParam Not used. 
lParam Not used. 
Return Value The return value contains the handle of the active MDI child window in its low word. If 


the window is maximized, the high word contains 1; otherwise, the high word is zero. 


WM_MDIICONARRANGE 


This message is sent to a multiple document interface (MDI) client window to arrange all 
minimized document child windows. It does not affect child windows that are not min- 


imized. 

Parameter Description 
wParam Not used. 
lParam Not used. 


WIM_MDIMAXIMIZE 


This message causes a multiple document interface (MDI) client window to maximize an 
MDI child window. When a child window is maximized, Windows resizes it to make its 
client area fill the client window. Windows places the child window’s System menu in the 


frame’s menu bar so that the user can restore or close the child window and adds the title 
of the child window to the frame window title. 
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Parameter Description 
wParam Contains the window identifier of the child window. 
[Param Not used. 
Comments If an MDI client window receives any message that changes the activation of its child 


windows, and if the currently active MDI child window is maximized, Windows restores 
the currently active child and maximizes the newly activated child. 


WM_MDINEXT 


This message activates the next multiple document interface (MDI) child window immedi- 
ately behind the currently active child window and places the currently active window be- 
hind all other child windows. 


Parameter Description 
wParam - Notused. 
lParam Not used. 
Comments If an MDI client window receives any message that changes the activation of its child 


windows, and if the currently active MDI child window is maximized, Windows restores 
the currently active child and maximizes the newly activated child. 


WM_MDIRESTORE 


This message restores a multiple document interface (MDI) child window from maximized 
or minimized size. 


Parameter Description 
wParam Contains the window identifier of the child window. 


[Param Not used. 
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WM_MDISETMENU 


This message replaces the menu of a multiple document interface (MDI) frame window, 
the Window pop-up menu, or both. 


Parameter Description 
wParam Not used. 
lParam Contains in its low-order word the menu handle (HMENU) of 


the new frame-window menu, and contains in its high-order 
word the menu handle of the new Window pop-up menu. If 
either word is zero, the corresponding menu is not changed. 


Return Value The return value is the handle of the frame-window menu replaced by this message. 


Comments After sending this message, an application must call the DrawMenuBar function to up- 
date the menu bar. 


If this message replaces the Window pop-up menu, MDI child-window menu items are re- 
moved from the previous Window menu and added to the new Window pop-up menu. 


If an MDI child window is maximized and this message replaces the MDI frame-window 
menu, the System menu and restore controls are removed from the previous frame-window 
menu and added to the new menu. 


WM_MDITILE 


This message causes a multiple document interface (MDI) client window to arrange all its 
child windows in a tiled format. 


Parameter Description 
wParam Not used. 
lParam Not used. 


WM_MEASUREITEM 


This message is sent to the owner of an owner-draw button, combo box, list box, or menu 
_ item when the control is created. When the owner receives the message, the owner fills in 
the MEASUREITEM data structure pointed to by the /Param message parameter and re- 
turns; this informs Windows of the dimensions of the control. If a list box or combo box is 
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created with the LBS_OWNERDRAWVARIABLE or CBS_LOWNERDRAWVARIABLE 


style, this message is sent to the owner for each item in the control. Otherwise, this 
message is sent once. 


Parameter Description 

wParam Not used. 

[Param Contains a long pointer to a MEASUREITEMSTRUCT data 
structure that contains the dimensions of the owner-draw con- 
trol. 

Comments Windows sends the WM_MEASUREITEM message to the owner of combo boxes and list 


boxes created with the OWNERDRAWEIXED style before sending WM_INITDIALOG. 


WM_MENUCHAR 


This message is sent when the user presses a menu mnemonic character that doesn’t match 
any of the predefined mnemonics in the current menu. It is sent to the window that owns 


the menu. 

Parameter Description 

wParam Contains the ASCII character that the user pressed. 
lParam 


The high-order word contains a handle to the selected menu. 
The low-order word contains the MF_POPUP flag if the menu is 


a pop-up menu. It contains the MF_SYSMENU flag if the menu 
is a System menu. 


Return Value The high-order word of the return value contains one of the following command codes: 


Code Meaning 


0 Informs Windows that it should discard the character that the 


user pressed, and creates a short beep on the system speaker. 
Informs Windows that it should close the current menu. 


Informs Windows that the low-order word of the return value 


contains the menu item-number for a specific item. This item is 
selected by Windows. 
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The low-order word is ignored if the high-order word contains zero or 1. Applications 
should process this message when accelerators are used to select bitmaps placed in a menu. 


WM_MENUSELECT 


This message occurs when the user selects a menu item. 


Parameter Description 


wParam Identifies the item selected. If the selected item is a menu item, 
wParam contains the menu-item ID. If the selected item contains a 
pop-up menu, wParam contains the handle of the pop-up menu. 


lParam The low-order word contains a combination of the following menu 
flags: 
Value’ Meaning 
MF_BITMAP Item is a bitmap. 
MF_CHECKED Item is checked. 
MF_DISABLED Item is disabled. 
MF_GRAYED Item is grayed. 
MF_MOUSESELECT Item was selected with a 

mouse. 

MF_OWNERDRAW Item is an owner-draw item. 
MF_POPUP Item contains a pop-up menu. 
MF_SYSMENU Item is contained in the System 


menu. The high-order word 
identifies the menu associated 
with the message. 


Comments If the low-order word of the /Param parameter contains —1 and the high-order word of the 
wParam parameter contains 0, Windows has closed the menu because the user pressed ESC 
or clicked outside the menu. 
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WM_MOUSEACTIVATE 


This message occurs when the cursor is in an inactive window and any mouse button is 
pressed. The parent receives this message only if the child passes it to the DefWindow- 
Proc function. 


Parameter Description 


wParam Contains a handle to the topmost parent window of the window 
being activated. 


lParam Contains the hit-test area code in the low-order word and the 
mouse message number in the high-order word. A hit test is a 
test that determines the location of the cursor. 


Comments If the child window passes the message to the DefWindowProc function, DefWindow- 
Proc passes this message to a window’s parent window before any processing occurs. If 
the parent window returns TRUE, processing is halted. 


For a description of the individual hit-test area codes, see Table 6.2, “Hit-Test Codes.” 


WM_MOUSEMOVE 


This message occurs when the user moves the mouse. 


Parameter Description 


wParam Contains a value that indicates whether various virtual keys are 
. down. It can be any combination of the following values: 


Value’ Meaning 

MK_CONTROL Set if CONTROL key is down. 
MK_LBUTTON Set if left button is down. 
MK_MBUTTON Set if middle button is down. 
MK_RBUTTON Set if right button is down. 
MK_SHIFT Set if SHIFT key is down. 


lParam . Contains the x- and y-coordinates of the cursor. The x-coordinate 
is in the low-order word; the y-coordinate is in the high-order 
word. These coordinates are always relative to the upper-left 
corer of the window. 
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Comments The MAKEPOINT macro can be used to convert the /Param parameter to a POINT struc- 
ture. 
WM_MOVE 
This message is sent after a window has been moved. 
Parameter Description 
wParam Is not used. 
lParam ' Contains the new location of the upper-left corner of the client 


area of the window. This new location is given in screen coordi- 
nates for overlapped and pop-up windows and parent-client 
coordinates for child windows. The x-coordinate is in the low- 
order word; the y-coordinate is in the high-order word. 


WM_NCACTIVATE 


This message is sent to a window when its nonclient area needs to be changed to indicate 
an active or inactive state. 


Parameter _ Description 


wParam Specifies when a caption bar or icon needs to be changed to indi- 
cate an active or inactive state. The wParam parameter is 
nonzero if an active caption or icon is to be drawn. It is zero for 
an inactive caption or icon. 


lParam Is not used. . 


Default Action The DefWindowProc function draws a gray caption bar for an inactive window and a 
black caption bar for an active window. 


WM_NCCALCSIZE 


This message is sent when the size of a window’s client area needs to be calculated. 
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Default Action 


Parameter Description 
wParam Is not used. 
[Param Points to a RECT data structure that contains the screen coordi- 


nates of the window rectangle (including client area, borders, 
caption, scroll bars, and so on). 


The DefWindowProc function calculates the size of the client area, based on the window 
characteristics (presence of scroll bars, menu, and so on), and places the result in the 
RECT data structure. 


WM_NCCREATE 


Return Value 


Default Action 


This message is sent prior to the WM_CREATE message when a window is first created. 


_ Parameter Description 


wParam Contains a handle to the window that is being created. 
lParam Points to the CREATESTRUCT data structure for the window. 


The return value is nonzero if the nonclient area is created. It is zero if an error occurs; ihe 
CreateWindow function will return NULL in this case. 


Scroll bars are initialized (the scroll-bar position and range are set) and the window text is 
set. Memory used internally to create and maintain the window is allocated. 


WM_NCDESTROY 


This message informs a window that its nonclient area is being destroyed. The Destroy- 
Window function sends the WM_NCDESTROY message to the window following the 
WM_DESTROY message. This message is used to free the allocated memory block as- 
sociated with the window. 


Parameter Description 
wParam Is not used. 


lParam Ts not used. 
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Default Action This message frees any memory internally allocated for the window. 


WM_NCHITTEST 


This message is sent to the window that contains the cursor (or the window that used the 
GetCapture function to capture the mouse input) every time the mouse is moved. 


Return Value 


Parameter 
wParam 


lParam 


Description 
Is not used. 


Contains the x- and y-coordinates of the cursor. The x-coordinate 
is in the low-order word; the y-coordinate is in the high-order 
word. These coordinates are always screen coordinates. 


The return value of the DefWindowProc function is one of the values given in Table 6.2, 
indicating the position of the cursor: 


Table 6.2 


Code 


HTBOTTOM 


HTBOTTOMLEFT 
HTBOTTOMRIGHT 


HTCAPTION 
HTCLIENT 
HTERROR 


HTGROWBOX 
HTHSCROLL 
HTLEFT 
HTMENU 
HTNOWHERE 
HTREDUCE 
HTRIGHT 
HTSIZE 
HTSYSMENU 
HTTOP 
HTTOPLEFT 


Hit-Test Codes 


Meaning 


In the lower horizontal border of window. 

In the lower-left corner of window border. 

In the lower-right corner of window border. | 
In a caption area. 

In aclient area. 


Same as HTNOWHERE except that the DefWindowProc function 
produces a system beep to indicate an error. 


In a size box. 

In the horizontal scroll bar. 

In the left border of window. 

In a menu area. 

On the screen background or on a dividing line between windows. 
In a minimize box. 

In the right border of window. 

Same as HTGROWBOX. 

In a control-menu box (close box in child windows). 

In the upper horizontal border of window. 


In the upper-left commer of window border. 
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Table 6.2 Hit-Test Codes (continued) 


Code Meaning 
HTTOPRIGHT In the upper-right corner of window border. 
HTTRANSPARENT In a window currently covered by another window. 
HTVSCROLL In the vertical scroll bar. 
HTZOOM In a maximize box. 
Comments The MAKEPOINT macro can be used to convert the /Param parameter to a POINT struc- 
ture. 


WM_NCLBUTTONDBLCLK 


This message is sent to a window when the user double-clicks the left mouse button while 
the cursor is within a nonclient area of the window. 


Parameter Description 

wParam _ Contains the code returned by WM_NCHITTEST (for more 
information, see the WM_NCHITTEST message, earlier in this 
chapter). 

lParam Contains a POINT data structure that contains the x- and y- 


screen coordinates of the cursor position. These coordinates are 
always relative to the upper-left corner of the screen. 


Default Action If appropriate, WM_SYSCOMMAND messages are sent. 


WM_NCLBUTTONDOWN 
This message is sent to a window when the user presses the left mouse button while the 


cursor is within a nonclient area of the window. 


Parameter Description 


wParam Contains the code returned by WM_NCHITTEST (for more 
information, see the WM_NCHITTEST message, earlier in this 
chapter). 
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Parameter Description 


lParam Contains a POINT data structure that contains the x- and y- 
screen coordinates of the cursor position. These coordinates are 
always relative to the upper-left corner of the screen. 


Default Action If appropriate, WM_SYSCOMMAND messages are sent. 


WM_NCLBUTTONUP 


This message is sent to a window when the user releases the left mouse button while the 
cursor is within a nonclient area of the window. 


Parameter Description 

wParam Contains the code returned by WM_NCHITTEST (for more 
information, see the WM_NCHITTEST message, earlier in this 
chapter). 

lParam Contains a POINT data structure that contains the x- and y- 


screen coordinates of the cursor position. These coordinates are 
always relative to the upper-left corner of the screen. 


Default Action If appropriate, WM_SYSCOMMAND messages are sent. 


WM_NCMBUTTONDBLCLK 


This message is sent to a window when the user double-clicks the middle mouse button 
while the cursor is within a nonclient area of the window. 


Parameter Description 

wParam Contains the code returned by WM_NCHITTEST (for more 
information, see the WM_NCHITTEST message, earlier in this 
chapter). 

lParam Contains a POINT data structure that contains the x- and y- 


screen coordinates of the cursor position. These coordinates are 
always relative to the upper-left corner of the screen. 
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WM_NCMBUTTONDOWN 


This message is sent to a window when the user presses the middle mouse button while the 
cursor is within a nonclient area of the window. 


Parameter Description 

wParam Contains the code returned by WM_NCHITTEST (for more 
information, see the WM_NCHITTEST message, earlier in this 
chapter). 

lParam Contains a POINT data structure that contains the x- and y- 


screen coordinates of the cursor position. These coordinates are 
always relative to the upper-left corner of the screen. 


WM_NCMBUTTONUP 


This message is sent to a window when the user releases the left mouse button while the 
cursor is within a nonclient area of the window. 


Parameter Description . 

wParam Contains the code returned by WM_NCHITTEST (for more 
information, see the WM_NCHITTEST message, earlier in this 
chapter). 

lParam Contains a POINT data structure that contains the x- and y- 


screen coordinates of the cursor position. These coordinates are 
always relative to the upper-left corner of the screen. 


WM_NCMOUSEMOVE 


This message is sent to a window when the cursor is moved within a nonclient area of the 


window. 
- Parameter Description 
wParam Contains the code returned by WM_NCHITTEST (for more 


information, see the WM_NCHITTEST message, earlier in this 
chapter). 
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Parameter Description 
lParam Contains a POINT data structure that contains the x- and y- 
screen coordinates of the cursor position. These coordinates are 
always relative to the upper-left corner of the screen. 
Default Action If appropriate, WM_SYSCOMMAND messages are sent. 
WM_NCPAINT 
This message is sent to a window when its frame needs painting. 
Parameter Description 
wParam Is not used. 
lParam Is not used. 
Default Action The DefWindowProc function paints the window frame. 
Comments An application can intercept this message and paint its own custom window frame. Re- 


member that the clipping region for a window is always rectangular, even if the shape of 
the frame is altered. 


WM_NCRBUTTONDBLCLK 


This message is sent to a window when the user double-clicks the right mouse button 
while the cursor is within a nonclient area of the window. 


Parameter Description 

wParam Contains the code returned by WM_NCHITTEST (for more 
information, see the WM_NCHITTEST message, earlier in this 
chapter). 

lParam Contains a POINT data structure that contains the x- and y- 


screen coordinates of the cursor position. These coordinates are 
always relative to the upper-left comer of the screen. 


Woes 
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WM_NCRBUTTONDOWN 


This message is sent to a window when the user presses the right mouse button while the 
cursor is within a nonclient area of the window. 


Parameter Description 

wParam Contains the code returned by WM_NCHITTEST (for more 
information, see the WM_NCHITTEST message, earlier in this 
chapter). 

lParam Contains a POINT data structure that contains the x- and y- 


screen coordinates of the cursor position. These coordinates are 
always relative to the upper-left corner of the screen. 


_ WM_NCRBUTTONUP 


This message is sent to a window when the user releases the right mouse button while the 
cursor is within a nonclient area of the window. . 


Parameter Description 

wParam Contains the code returned by WM_NCHITTEST (for more 
information, see the WM_NCHITTEST message, earlier in this 
chapter). 

lParam Contains a POINT data structure that contains the x- and y- 


screen coordinates of the cursor position. These coordinates are 
always relative to the upper-left corner of the screen. 


WM_NEXTDLGCTL 


This message is sent to a dialog box’s window function, to alter the control focus. The ef- 
fect of this message is different than that of the SetFocus function because 
WM_NEXTDLGCTL modifies the border around the default button. 
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Parameter Description 


’ wParam If the /Param parameter is nonzero, the wParam parameter iden- 
tifies the control that receives the focus. If [Param is zero, 
wParam is a flag that indicates whether the next or previous con- 
trol with tab-stop style receives the focus. If wParam is zero, the 
next control receives the focus; otherwise, the previous control 
with tab-stop style receives the focus. 


lParam Contains a flag that indicates how Windows uses the wParam 
parameter. If the /Param parameter is nonzero, wParam is a 
handle associated with the control that receives the focus; other- 
wise, wParam is a flag that indicates whether the next or 
previous control with tab-stop style receives the focus. 


Comments Do not use the SendMessage function to send a WM_NEXTDLGCTL message if your 
application will concurrently process other messages that set the control focus. Use the 
PostMessage function instead. 


WM_PAINT 


This message is sent when Windows or an application makes a request to repaint a portion 
of an application’s window. The message is sent either when the UpdateWindow function 
is called or by the DispatchMessage function when the application obtains a WM_PAINT 
message by using the GetMessage or PeekMessage function. 


Parameter Description 
wParam _Is not used. 
lParam Is not used. 


WM_PAINTCLIPBOARD 


This message is sent when the clipboard contains a data handle for the CF_OWNERDIS- 
PLAY format (specifically the clipboard owner should display the clipboard contents) and 
the Clipboard application’s client area needs repainting. The WM_PAINTCLIPBOARD 
message is sent to the clipboard owner to request repainting of all or part of the Clipboard 
application’s client area. 
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Parameter | Description 
wParam Contains a handle to the Clipboard-application window. 
lParam The low-order word of the /Param parameter identifies a 


PAINTSTRUCT data structure that defines what part of the 
client area to paint. The high-order word is not used. 


Comments To determine whether the entire client area or just a portion of it needs repainting, the clip- 
board owner must compare the dimensions of the drawing area given in the repaint field 
of the PAINTSTRUCT data structure to the dimensions given in the most recent 
WM_SIZECLIPBOARD message. 


An application must use the GlobalLock function to lock the memory that contains the 
PAINTSTRUCT data structure. The application should unlock that memory by using the 
GlobalUnlock function before it yields or returns control. 


WM_PAINTICON 


This message is sent to a minimized (iconic) window when the icon is to be painted. A 
window receives this message only if a class icon is defined for the window. Otherwise, 
WM_PAINT is sent instead. Passing this message to the DefWindowProc function per- 
mits Windows to paint the icon with the class icon. 


Parameter Description 
wParam Is not used. 
[Param Is not used. 


WM_PALETTECHANGED 


This message informs all windows that the window with input focus has realized its logical 
palette, thereby changing the system palette. This message allows windows without input 
focus that use a color palette to realize their logical palettes and update their client areas. 


Parameter: Description 


wParam Contains the handle of the window that caused the system 
palette to change. 


lParam Is not used. 
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WmM_PARENTNOTIFY 


Comments 


To avoid creating a loop, a window that receives this message should not realize its palette 
unless it determines that wParam does not contain its window handle. 


WM_PARENTNOTIFY 


Comments 


This message is sent to the parent of a child window when the child window is created or 
destroyed, or when the user has pressed a mouse button while the cursor is over the child 
window. When the child window is being created, Windows sends WM_PARENT- 
NOTIFY just before the CreateWindow or CreateWindowEx function that creates the 
window returns. When the child window is being destroyed, Windows sends the message 
before any processing to destroy the window takes place. 


Parameter Description 


wParam Specifies the event for which the parent is being notified. It can 
be any of these values: 


Value Meaning 

WM_CREATE The child window is being 

. created. 

WM_DESTROY The child window is being de- 
stroyed. 


WM_LBUTTONDOWN The user has clicked on a child 
WM_MBUTTONDOWN window. 
WM_RBUTTONDOWN 


lParam Contains the window handle of the child window in its low- 
order word and the ID of the child window in its high-order 
word. 


This message is also sent to all ancestor windows of the child window, including the top- 
level window. 


This message is sent to the parent of all child windows unless the child has the extended 
window style WS_EX_NOPARENTNOTIFY; CreateWindowEx creates a window with 
extended window styles. By default, child windows in a dialog box have the WS_EX_NO- 
PARENTNOTIFY style unless the child window was created by calling the Create Win- 
dowEx function. 


AA 


WM_PASTE 
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WM_PASTE 


This message inserts the data from the clipboard into the control window at the current 
cursor position. Data are inserted only if the clipboard contains data in CF_TEXT format. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 


-WM_QUERYDRAGICON 


Return Value 


This message is sent to a minimized (iconic) window which is about to be dragged by the 
user but which does not have an icon defined for its class. 


When the user drags the icon of a window without a class icon, Windows replaces the icon 
with a default icon cursor. If the application needs a different cursor to be displayed during 
dragging, it must return the handle of a monochrome cursor compatible with the display 
driver’s resolution. The application can call the LoadCursor function to load a cursor 
from the resources in its executable file and to obtain this handle. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 


The return value contains in its low-order word the handle of the cursor which Windows is 
to display while the user drags the icon. The return yalue is NULL if Windows is to display 
the default icon cursor. The default return value is NULL. 


WM_QUERYENDSESSION 


This message is sent when the user chooses the End Session command. If any application 
returns zero, the session is not ended. Windows stops sending WM_QUERYENDSES- 
SION messages as soon as one application returns zero, and sends WM_ENDSESSION 


messages, with the wParam parameter set to zero, to any applications that have already re- 
turned nonzero. 
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WM_QUERYNEWPALETTE 


Return Value 


Default Action 


Parameter Description 
wParam Is not used. 
[Param Is not used. 


The return value is nonzero if the application can be conveniently shut down. Otherwise, it 
is zero. 


The DefWindowProc function returns nonzero. 


WM_QUERYNEWPALETTE 


Return Value 


This message informs a window that it is about to receive input focus. If the window real- 
izes its logical palette when it receives input focus, the window should return TRUE; other- 
wise, it should retum FALSE. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 


The return value is TRUE if the window realizes its logical palette. Otherwise, it is FALSE. 


WM_QUERYOPEN 


Return Value 


Default Action 


This message is sent to an icon when the user requests that it be opened into a window. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 


The return value is zero when the application prevents the icon from being opened. It is 
nonzero when the icon can be opened. 


The DefWindowProc function returns nonzero. 
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WM_QUIT 


This message indicates a request to terminate an application and is generated when the 
application calls the PostQuitMessage function. It causes the GetMessage function to re- 


turn zero. 

-Parameter Description 

wParam Contains the exit code given in the PostQuitMessage call. 
lParam Is not used. 


WM_RBUTTONDBLCLK 


This message occurs when the user double-clicks the right mouse button. 


Parameter Description 


wParam Contains a value that indicates whether various virtual keys are 
down. It can be any combination of the following values: 


Value Meaning 

MK_CONTROL Set if CONTROL key is down. 
MK_LBUTTON Set if left button is down. 
MK_MBUTTON Set if middle button is down. 
MK_RBUTTON Set if right button is down. 
MK_SHIFT Set if SHIFT key is down. 


lParam Contains the x- and y-coordinates of the cursor. The x-coordinate 
is in the low-order word; the y-coordinate is in the high-order 
word. These coordinates are always relative to the upper-left 
comer of the window. 


Comments Only windows whose window class has CS_DBLCLKS style can receive double-click 
messages. Windows generates a double-click message when the user presses, releases, and 
then presses a mouse button again within the system’s double-click time limit. Double- 
clicking actually generates four messages: a down-click message, an up-click message, the 
double-click message, and another up-click message. 
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WM_RBUTTONDOWN 


WM_RBUTTONDOWN 


This message occurs when the user presses the right mouse button. 


Parameter 


wParam 


[Param 


WM_RBUTTONUP 


Description 


Contains a value that indicates whether various virtual keys are 
down. It can be any combination of the following values: 


Value Meaning 

MK_CONTROL Set if CONTROL key is down. 
MK_LBUTTON Set if left button is down. 
MK_MBUTTON Set if middle button is down. 
MK_SHIFT Set if SHIFT key is down. 


Contains the x- and y-coordinates of the cursor. The x-coordinate 
is in the low-order word; the y-coordinate is in the high-order 
word. These coordinates are always relative to the upper-left 
corner of the window. 


This message occurs when the user releases the right mouse button. 


Parameter 


wParam 


lParam 


Description 


Contains a value that indicates whether various virtual keys are 
down. It can be any combination of the following values: 


Value Meaning 


MK_CONTROL Set if CONTROL key is down. 
MK_LBUTTON Set if left button is down. 
MK_MBUTTON - Set if middle button is down. 
MK_SHIFT Set if SHIFT key is down. 


Contains the x- and y-coordinates of the cursor. The x-coordinate 
is in the low-order word; the y-coordinate is in the high-order 
word. These coordinates are always relative to the upper-left 
corner of the window. 
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WM_RENDERALLFORMATS 


Comments 


This message is sent to the application that owns the clipboard when that application is 
being destroyed. 


Parameter Description 
wParam Is not used. 
[Param Is not used. 


The application should render the clipboard data in all the formats it is capable of generat- 
ing and pass a handle to each format to the SetClipboardData function. This ensures that 
the data in the clipboard can be rendered even though the application has been destroyed. 


WM_RENDERFORMAT 


This message requests that the clipboard owner format the data last copied to the clipboard 
in the specified format, and then pass a handle to the formatted data to the clipboard. 


Parameter Description 


wParam Specifies the data format. It can be any one of the formats de- 
| scribed with the SetClipboardData function. 


[Param Is not used. 


WM_SETCURSOR 


Comments 


_ This message occurs if mouse input is not captured and the mouse causes cursor move- 


ment within a window. 


Parameter Description 
wParam Contains a handle to the window that contains the cursor. 
lParam Contains the hit-test area code in the low-order word and the 


mouse message number in the high-order word. 


The DefWindowProc function passes the WM_SETCURSOR message to a parent 
window before processing. If the parent window returns TRUE, further processing is 
halted. Passing the message to a window’s parent window gives the parent window control 
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over the cursor’s setting in a child window. The DefWindowProc function also uses this 
message to set the cursor to an arrow if it is not in the client area, or to the registered-class 
cursor if it is. If the low-order word of the /Param parameter is HTERROR and the high- 


order word of /Param is a mouse button-down message, the MessageBeep function is 
called. 


The high-order word of /Param is zero when the window enters menu mode. 


WM_SETFOCUS 


This message is sent after a window gains the input focus. 


Parameter Description 
wParam Contains the handle of the window that loses the input focus : 
(may be NULL). 
lParam Is not used. 
Comments To display a caret, an application should call the appropriate caret functions at this point. 


WM_SETFONT 


This message specifies the font that a dialog box control is to use when drawing text. The 
best time for the owner of a dialog box control to set the font of the control is when it re- 
ceives the WM_INITDIALOG message. The application should call the DeleteObject 


function to delete the font when it is no longer needed, such as after the control is de- 
stroyed. 


The size of the control is not changed as a result of receiving this message. To prevent 
Windows from clipping text that does not fit within the boundaries of the control, the appli- 
cation should correct the size of the control window before changing the font. 


Parameter Description 


wParam Contains the handle of the font. If this parameter is NULL, the 
control will draw text using the default system font. 


lParam Specifies whether the control should be redrawn immediately 
upon setting the font. Setting param to TRUE causes the control 
to redraw itself; otherwise, it will not. 
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Comments 


Before Windows creates a dialog box with the DS_SETFONT style, Windows sends the 
WM_SETFONT message to the dialog-box window before creating the controls. An appli- 
cation creates a dialog box with the DS_SETFONT style by calling any of the following 
functions: : 

= CreateDialogIndirect 

= CreateDialogIndirectParam 

= DialogBoxIndirect 

= DialogBoxIndirectParam 

The DLGTEMPLATE data structure which the application passes to these functions must 


have the DS_SETFONT style set and must contain a FONTINFO data structure that de- 
fines the font with which the dialog box will draw text. 


WM_SETREDRAW 


Comments 


WM_SETTEXT 


This message is sent by an application to a window in order to allow changes in that 
window to be redrawn, or to prevent changes in that window from being redrawn. 


Parameter Description 

wParam Specifies the state of the redraw flag. If the wParam parameter 
is nonzero, the redraw flag is set. If wParam is zero, the flag is 
cleared. 

lParam Is not used. 


This message sets or clears the redraw flag. However, it does not direct a list box to update 
its display. When the redraw flag is set, a control can be redrawn immediately after each 
change. When the redraw flag is cleared, no redrawing is done. Applications that need to 
add several names to a list without redrawing until the final name is added should set the 
redraw flag before adding the final name to the list. 


This message is used to set the text of a window. For edit controls and combo-box edit con- 
trols, the text to be set is the content of the edit control. For button controls, the text is the 
button name. For other windows, the text is the window caption. 
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Parameter Description 
wParam Is not used. 
IParam Points to a null-terminated string that is the window text. 


Return Value The return value is LB_ERRSPACE (for a list box) or CB_LERRSPACE (for a combo box) 
if insufficient space is available to set the text in the edit control. It is CB_ERR if this 
message is sent to a combo box without an edit control. 


Comments This message does not change the current selection in the list box of a combo box. An 
application should use the CB_SELECTSTRING message to select the list-box item which 
matches the text in the edit control. 


WM_SHOWWINDOW 


This message is sent when a window is to be hidden or shown. A window is hidden or 
shown when the ShowWindow function is called; when an overlapped window is maxi- 
mized or restored; or when an overlapped or pop-up window is closed (made iconic) or 
opened (displayed on the screen). When an overlapped window is closed, all pop-up 
windows associated with that window are hidden. 


Parameter Description 


wParam Specifies whether a window is being shown. It is nonzero if the 
window is being shown. It is zero if the window is being hidden. 


lParam Specifies the status of the window being shown. It is zero if the 
message is sent because of a ShowWindow function call. Otherwise, 
the /Param parameter is one of the following values: 


Value Meaning 


SW_PARENTCLOSING Parent window is closing (being 
made iconic) or a pop-up 
window is being hidden. 


SW_PARENTOPENING Parent window is opening 
(being displayed) or a pop-up 
window is being shown. 


Default Action The DefWindowProc function hides or shows the window as specified by the message. 
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WM_SIZE 
This message is sent after the size of a window has changed. 
Parameter Description 
wParam Contains a value that defines the type of resizing requested. It can be 


one of the following values: 


Value Meaning 

SIZEFULLSCREEN Window has been maximized. 

SIZEICONIC Window has been minimized. 

SIZENORMAL Window has been resized, but 
neither SIZEICONIC nor SIZE- 
FULLSCREEN applies. 

SIZEZOOMHIDE Message is sent to all pop-up 


windows when some other 
window is maximized. 


SIZEZOOMSHOW Message is sent to all pop-up 
windows when some other 
window has been restored to its 


former size. 
lParam Contains the new width and height of the client area of the window. 
The width is in the low-order word; the height is in the high-order 
word. 
Comments If the SetScrollPos or MoveWindow function is called for a child window as a result of 


the WM_SIZE message, the bRedraw parameter should be nonzero to cause the window to 
be repainted. 


WM_SIZECLIPBOARD 


This message is sent when the clipboard contains a data handle for the CF_OWNERDIS- 
PLAY format (that is, the clipboard owner should display the clipboard contents) and the 
clipboard-application window has changed size. 
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WM_SPOOLERSTATUS 


Parameter Description 
wParam Identifies the clipboard-application window. 
lParam The low-order word of the /Param parameter identifies a RECT 
data structure that specifies the area the clipboard owner should 
paint. The high-order word is not used. 
Comments A WM_SIZECLIPBOARD message is sent with a null rectangle (0,0,0,0) as the new size 


when the clipboard application is about to be destroyed or minimized. This permits the 
clipboard owner to free its display resources. 


An application must use the GlobalLock function to lock the memory that contains the 
PAINTSTRUCT data structure. The application should unlock that memory by using the 
GlobalUnlock function before it yields or returns control. 


WM_SPOOLERSTATUS 


This message is sent from Print Manager whenever a job is added to or removed from the 


Print Manager queue. 


Parameter Description 
wParam Is set to SP_JOBSTATUS. 
[param Specifies in its low-order word the number of jobs remaining in 
the Print Manager queue. The high-order word is not used. 
Comments This message is for informational purposes only. 


WIM_SYSCHAR 


This message results when a WM_SYSKEYUP and WM_SYSKEYDOWN message are 
translated. It specifies the virtual-key code of the System-menu key. 


Parameter 
wParam 


lParam 


Description 
Contains the ASCII-character key code of a System-menu key. 


Contains the repeat count, scan code, key-transition code, pre- 
vious key state, and context code, as shown in the following list: 


WM_SYSCHAR 


Default Action 


Comments 


Parameter Description 
Bit 
0-15 (low-order 


word) 


16-23 (low byte 
of high-order 
word) 


24 


25-26 
27-28 
29 


30 


31 


None. 
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Value 


Repeat count (the number of times the 
key stroke is repeated as a result of the 
user holding down the key). 


Scan code (OEM-dependent value). 


Extended key, such as a function key or a 
key on the numeric key pad (1 if it is an 
extended key, 0 otherwise). 


Not used. 
Used internally by Windows. 


Context code (1 if the ALT key is held 
down while the key is pressed, 0 other- 
wise). 


Previous key state (1 if the key is down 
before the message is sent, 0 if the key is 


up). 


Transition state (1 if the key is being 
released, O if the key is being pressed). 


When the context code is zero, the message can be passed to the TranslateAccelerator 
function, which will handle it as though it were a normal key message instead of a system- 
key message. This allows accelerator keys to be used with the active window even if the 


active window does not have the input focus. 


For IBM Enhanced 101- and 102-key keyboards, enhanced keys are the right ALT and the 
right CONTROL keys on the main section of the keyboard; the INSERT, DELETE, HOME, END, 
PAGE UP, PAGE DOWN and DIRECTION keys in the clusters to the left of the numeric key 
pad; and the divide (/) and ENTER keys in the numeric key pad. Some other keyboards may 
support the extended-key bit in the /Param parameter. 


6-105 | — WM_SYSCOLORCHANGE 


WM_SYSCOLORCHANGE 


This message specifies a change in one or more system colors. Windows sends the 
message to all top-level windows when a change is made in the system color setting. 


Parameter Description 
wParam Is not used. 
[Param Is not used. 
Default Action Windows sends a WM_PAINT message to any window that is affected by a system color 
change. 
Comments Applications that have brushes that use the existing system colors should delete those 


brushes and re-create them by using the new system colors. 


WM_SYSCOMMAND 


This message is sent when the user selects a command from the System menu or when the 
user selects the maximize or minimize box. 


Parameter Description 


wParam Specifies the type of system command requested. It can be any one 
of the following values: 


Value Meaning 

SC_CLOSE Close the window. 

SC_HSCROLL Scroll horizontally. 

SC_KEYMENU Retrieve a menu through a key 
. stroke. 

SC_MAXIMIZE Maximize the window. 

(or SC_ZOOM) 

SC_MINIMIZE Minimize the window. 

(or SC_ICON) 

SC_MOUSEMENU Retrieve a menu through a 


mouse click. 
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Default Action 


Comments 


Parameter Description 
Value Meaning 
SC_MOVE Move the window. 
SC_NEXTWINDOW Move to the next window. 
SC_PREVWINDOW Move to the previous window. 
SC_RESTORE Checkpoint (save the previous 

coordinates). 

SC_SIZE Size the window. 
SC_VSCROLL Scroll vertically. 

lParam Contains the cursor coordinates if a System-menu command is 


chosen with the mouse. The low-order word contains the x-coordi- 
nate, and the high-order word contains the y-coordinate. Otherwise, 
this parameter is not used. 


The DefWindowProc function carries out the System-menu request for the predefined ac- 
tions specified above. 


In WM_SYSCOMMAND messages, the four low-order bits of the wParam parameter are 
used internally by Windows. When an application tests the value of wParam, it must com- 
bine the value OxFFFO with the wParam value by using the bitwise AND operator to ob- 
tain the correct result. 


The menu items in a System menu can be modified by using the GetSystemMenu, Ap- 
pendMenu, InsertMenu, and ModifyMenu functions. Applications that modify the Sys- 
tem menu must process WM_SYSCOMMAND messages. Any WM_SYSCOMMAND 
messages not handled by the application must be passed to the DefWindowProc function. 
Any command values added by an application must be processed by the application and . 
cannot be passed to DefWindowProc. 


An application can carry out any system command at any time by passing a WM_SYS- 
COMMAND message to the DefWindowProc function. 


Accelerator key strokes that are defined to select items from the System menu are trans- 
lated into WM_SYSCOMMAND messages; all other accelerator pkey strokes are translated 
into WM_COMMAND messages. 
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WM_SYSDEADCHAR 


This message results when a WM_SYSKEYUP and WM_SYSKEYDOWN message are 
translated. It specifies the character value of a dead key. 


Parameter Description 
wParam Contains the dead-key character value. 
lParam Contains a repeat count and an auto-repeat count. The low-order 


word contains the repeat count; the high-order word contains the 
auto-repeat count. 


WM_SYSKEYDOWN 


This message is sent when the user holds down the ALT key and then presses another key. 
It also occurs when no window currently has the input focus; in this case, the WM_SYS- 
KEYDOWN message is sent to the active window. The window that receives the message 
can distinguish between these two contexts by checking the context code in the /Param 


parameter. 

Parameter Description 

wParam Contains the virtual-key code of the key being pressed. 
[Param Contains the repeat count, scan code, key-transition code, pre- 


vious key state, and context code, as shown in the following list: 


Bit. Value 

0-15 (low-order Repeat count (the number of times the 

word) key stroke is repeated as a result of the 
user holding down the key). 

16—23 (low byte Scan code (OEM-dependent value). 

of high-order 

word) 

24 Extended key, such as a function key ora 
key on the numeric key pad (1 if it is an 
extended key). 

25-26 Not used. 


27-28 Used internally by Windows. 
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Comments 


Parameter Description 
; Bit Value 

29 Context code (1 if the ALT key is held 
down while the key is pressed, 0 other- 
wise). 

30 Previous key state (1 if the key is down 
before the message is sent, 0 if the key is 
up). 

31 Transition state (1 if the key is being 


released, 0 if the key is being pressed). 


For WM_SYSKEYDOWN messages, the key-transition bit (bit 
31) is 0. The context-code bit (bit 29) is 1 if the ALT key is down 
while the key is pressed; it is 0 if the message is sent to the ac- 
tive window because no window has the input focus. 


When the context code is zero, the message can be passed to the TranslateAccelerator 
function, which will handle it as though it were a normal key message instead of a system- 
key message. This allows accelerator keys to be used with the active window even if the 
active window does not have the input focus. 


Because of auto-repeat, more than one WM_SYSKEYDOWN message may occur before 
a WM_SYSKEYUP message is sent. The previous key state (bit 30) can be used to deter- 
mine whether the WM_SYSKEYDOWN message indicates the first down transition or a 
repeated down transition. 


For IBM Enhanced 101- and 102-key keyboards, enhanced keys are the right ALT and the 
right CONTROL keys on the main section of the keyboard; the INSERT, DELETE, HOME, END, 
PAGE UP, PAGE DOWN and DIRECTION keys in the clusters to the left of the numeric key 
pad; and the divide (/) and ENTER keys in the numeric key pad. Some other keyboards may 
support the extended-key bit in the /Param parameter. 


WM_SYSKEYUP 


This message is sent when the user releases a key that was pressed while the ALT key was 
held down. It also occurs when no window currently has the input focus; in this case, the 
WM_SYSKEYUP message is sent to the active window. The window that receives the 
message can distinguish between these two contexts by checking the context code in the 
[Param parameter. 


6-109 WM_SYSKEYUP 
Parameter Description 
wParam Contains the virtual-key code of the key being released. 
lParam Contains the repeat count, scan code, key-transition code, pre- 
vious key state, and context code, as shown in the following list: 

Bit Value 

0-15 (low-order Repeat count (the number of times the 

word) key stroke is repeated as a result of the 
user holding down the key). 

16-23 (low byte Scan code (OEM-dependent value). 

of high-order 

word) 

24 Extended key, such as:a function key ora 
key on the numeric key pad (1 if it is an 
extended key). 

25-26 Not used. 

27-28 Used internally by Windows. 

29 Context code (1 if the ALT key is held 
down while the key is pressed, O other- 
wise). 

30 Previous key state (1 if the key is down 
before the message is sent, 0 if the key is 
up). 

31 Transition state (1 if the key is being 
released, 0 if the key is being pressed). 

For WM_SYSKEYUP messages, the key-transition bit (bit 31) 

is 1. The context-code bit (bit 29) is | if the ALT key is down 

while the key is pressed; it is 0 if the message is sent to the ac- 
tive window because no window has the input focus. 
Comments When the context code is zero, the message can be passed to the TranslateAccelerator 


function, which will handle it as though it were a normal key message instead of a system- 
key message. This allows accelerator keys to be used with the active window even if the 


active window does not have the input focus. 


For IBM Enhanced 101- and 102-key keyboards, enhanced keys are the right ALT and the 
right CONTROL keys on the main section of the keyboard; the INSERT, DELETE, HOME, END, 
PAGE UP, PAGE DOWN and DIRECTION keys in the clusters to the left of the numeric key 
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pad; and the divide (/) and ENTER keys in the numeric key pad. Some other keyboards may 
support the extended-key bit in the /Param parameter. 


For non-USA Enhanced 102-key keyboards, the right ALT key is handled as a CONTROL- 
ALT key. The following shows the sequence of messages which result when the user 
presses and releases this key: 


Order Message Virtual-key code (/Param) 
1 WM_KEYDOWN VK_CONTROL 

2 WM_KEYDOWN VK_MENU 

3 WM_KEYUP VK_CONTROL 

4 WM_SYSKEYUP | VK_MENU 


WM_TIMECHANGE 


Comments 


WM_TIMER 


This message occurs when an application makes a change (or set of changes) to the system 
time. Any application that changes the system time should send this message to all top- 
level windows. 


Parameter Description 
wParam Is not used. 
[Param Is not used. 


To send the WM_TIMECHANGE message to all top-level windows, an application can 
use the SendMessage function with the hWnd parameter set to OXFFFF. 


This message occurs when the time limit set for a given timer has elapsed. 
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WM_UND 


WM_UNDO 


Parameter Description 
wParam Contains the timer ID, an integer value that identifies the timer. 
lParam Points to a function that was passed to the SetTimer function 


when the timer was created. If the Param parameter is not 
NULL, Windows calls the specified function directly, instead of 
sending the WM_TIMER message to the window function. 


This message undoes the last operation. When sent to an edit control, the previously de- 
leted text is restored or the previously added text is deleted. 


Parameter Description 
wParam Is not used. 
lParam Is not used. 


WM_VKEYTOITEM 


Return Value 


This message is sent by a list box with the LBS_WANTKEYBOARDINPUT style to its 
owner in response to a WM_KEYDOWN message. 


Parameter Description 
wParam Contains the virtual-key code of the key which the user pressed. 
lParam Contains the current caret position in its high-order word and the 


window handle of the list box in its low-order word. 


The return value specifies the action which the application performed in response to the 
message. A return value of —2 indicates that the application handled all aspects of selecting 
the item and wants no further action by the list box. A return value of —1 indicates that the 
list box should perform the default action in response to the key stroke. A return value of 
zero or greater specifies the index of an item in the list box and indicates that the list box 
should perform the default action for the key stroke on the given item. 
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WM_VSCROLL 
This message is sent when the user clicks the vertical scroll bar. 
Parameter Description 
wParam Contains a scroll-bar code that specifies the user’s scrolling request. 


It can be any one of the following values: 


SB_BOTTOM 
SB_ENDSCROLL 
SB_LINEDOWN™ 
SB_LINEUP 
SB_PAGEDOWN 
SB_PAGEUP 
SB_THUMBPOSITION 


SB_THUMBTRACK 


SB_TOP 


Meaning 


Scroll to bottom. 

End scroll. 

Scroll one line down. 
Scroll one line up. 
Scroll one page down. 
Scroll one page up. 


Scroll to absolute position. The 
current position is provided in 
the low-order word of /Param. 


Drag thumb to specified posi- 
tion. The current position is 
provided in the low-order word 
of /Param. 


Scroll to top. 


lParam If the message is sent by a scroll-bar control, the high-order word of 
the /Param parameter identifies the control. If the message is sent as 
a result of the user clicking a pop-up window’s scroll bar, the high- 


order word is not used. 


Comments The SB_THUMBTRACK message typically is used by applications that give some feed- 


back while the thumb is being dragged. 


If an application scrolls the document in the window, it must also reset the position of the 


thumb by using the SetScrollPos function. 
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WM_VSCROLLCLIPBOARD 


This message is sent when the clipboard contains a data handle for the CF_OWNERDIS- 
PLAY format (that is, the clipboard owner should display the clipboard contents) and an 
event occurs in the clipboard-application’s vertical scroll bar. 


Parameter Description 

wParam Contains a handle to the clipboard-application window. 

lParam Contains one of the following scroll-bar codes in the low-order word: 
Value Meaning 
SB_BOTTOM Scroll to lower right. 
SB_ENDSCROLL End scroll. 
SB_LINEDOWN Scroll one line down. 
SB_LINEUP Scroll one line up. 
SB_PAGEDOWN Scroll one page down. 
SB_PAGEUP Scroll one page up. 
SB_THUMBPOSITION Scroll to absolute position. 
SB_TOP Scroll to upper left. 


The high-order word of the /Param parameter contains the thumb 
position if the scroll-bar code is SB_THUMBPOSITION. Otherwise, 
the high-order word is not used. 


Comments The clipboard owner should use the InvalidateRect function or repaint as desired. The 
scroll bar position should also be reset. 
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WM_WININICHANGE 
This message is sent when the Windows initialization file, WIN.INI, changes. Any applica- 
tion that makes a change to WIN.INI should send this message to all top-level windows. 


Parameter Description 
wParam Is not used. 
/[Param Points to a string that specifies the name of the section that has 


changed (the string does not include the square brackets). 


Comments To send the WM_WININICHANGE message to all top-level windows, an application can 
, use the SendMessage function with the hWnd parameter set to OXFFFF. 


Although it is incorrect to do so, some applications send this message with /Param set to 
NULL. If an application receives this message with a NULL /Param, it should check all 
sections in WIN.INI that affect the application. 


Part || General Reference 


Part 3 provides general reference information on components of the Windows 
application programming interface that are in addition to the functions and mes- 
sages described in the preceding parts. 
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10 Module-Definition Statements 
11. ~—_‘~-Binary and Ternary Raster-Operation Codes 
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Chapter || Data Types and Structures 


This chapter describes the data types and structures used by Microsoft Windows 
functions and messages. It contains two parts: a table of data types and a list of 
Windows data structures, each arranged alphabetically. 


7.1 Data Types 


The data types in the following list are key words that define the size and 
meaning of parameters and return values associated with Windows functions. 
This list contains character, integer, and Boolean types, pointer types, and han- 
dles. The character, integer, and Boolean types are common to most C compilers. 
Most of the pointer-type names begin with either a P prefix (for short pointers) or 
an LP prefix (for long pointers). A short pointer accesses data within the current 
data segment; a long pointer contains a 32-bit segment/offset value. A Windows 
application uses a handle to refer to a resource that has been loaded into memory. 
Windows provides access to these resources through internally maintained tables 
that contain individual entries for each handle. Each entry in the handle table con- 
tains the address of the resource and a means of identifying the resource type. 

The Windows data types are defined in the following list: 


Type Definition 

BOOL 16-bit Boolean value. 

BYTE Unsigned 8-bit integer. 

char ASCII character or a signed 8-bit in- 
teger. 

DWORD '  _Unsigned 32-bit integer or a seg- 
ment/offset address. 

FAR Data-type attribute that can be used to 


create a long pointer. 


FARPROC Long pointer to a function obtained by 
calling the MakeProcInstance func- 
tion. 
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Type 


GLOBALHANDLE 


HANDLE 
HBITMAP 
HBRUSH 


HCURSOR 


HDC 
HFONT 


HICON 
HMENU 


HPALETTE 


’ HPEN 


HRGN 


HSTR 


int 


Definition 


Handle to global memory. It is a 16-bit 
index to a block of memory allocated 
from the system’s global heap. 


General handle. It represents a 16-bit 
index to a table entry that identifies pro- 
gram data. 


Handle to a physical bitmap. It is a 16- 
bit index to GDI’s physical drawing 
objects. 


Handle to a physical brush. It is a 16-bit 
index to GDI’s physical drawing ob- 
jects. 


Handle to a cursor resource. It is a 16- 
bit index to a resource-table entry. 


Handle to a display context. It is a 16- 
bit index to GDI’s device-context 
tables. 


Handle to a physical font. It is a 16-bit 
index to GDI’s physical drawing ob- 
jects. 


Handle to an icon resource. It is a 16- 
bit index to a resource-table entry. 


Handle to a menu resource. It is a 16- 
bit index to a resource-table entry. 


Handle to a logical palette. It is a 16-bit 
index to GDI’s physical drawing ob- 
jects. 


Handle to a physical pen. It is a 16-bit 
index to GDI’s physical drawing ob- 
jects. 


Handle to a physical region. It is a 16- 
bit index to GDI’s physical drawing 
objects. 


Handle to a string resource. It is a 16- 
bit index to a resource-table entry. 


Signed 16-bit integer. 


| Type 
LOCALHANDLE 


long 
- LONG 
LPBITMAP 


LPBITMAPCOREHEADER 
LPBITMAPCOREINFO 
LPBITMAPFILEHEADER 
LPBITMAPINFO 
LPBITMAPINFOHEADER 
LPCOMPAREITEMSTRUCT 
LPCREATESTRUCT 
LPDELETEITEMSTRUCT 
LPDRAWITEMSTRUCT 
LPHANDLETABLE 


LPINT 
LPLOGBRUSH 


LPLOGFONT 


LPLOGPALETTE 


Data Types and Structures 7-3 


Definition 


Handle to local memory. It is a 16-bit 
index to a block of memory allocated 
from the application’s local heap. 


Signed 32-bit integer. 
Signed 32-bit integer. 


Long pointer to a BITMAP data struc- 
ture. 


Long pointer to a BITMAPCORE- 
HEADER data structure. 


Long pointer to a BITMAPCORE- 
INFO data structure. 


Long pointer to a BITMAPFILE- 
HEADER data structure. 


Long pointer to a BITMAPINFO data 
structure. 


Long pointer to a BITMAPINFO- 
HEADER data structure. 


Long pointer to a COMPAREITEM- 
STRUCT data structure. 


Long pointer toa CREATESTRUCT 
data structure. 


Long pointer toa DELETEITEM- 
STRUCT data structure. 


Long pointer to a DRAWITEM- 
STRUCT data structure. 


Long pointer toa HANDLETABLE 
data structure. 


Long pointer to a signed 16-bit integer. 


Long pointer to a LOGBRUSH data 
structure. 


Long pointer to a LOGFONT data 
structure. 


Long pointer to a LOGPALETTE data 
structure. 
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Type 
LPLOGPEN 


LPMEASUREITEMSTRUCT 


LPMETAFILEPICT 


LPMSG 
LPOFSTRUCT 


LPPAINTSTRUCT 


LPPALETTEENTRY 


LPPOINT 
LPRECT 
LPRESOURCELIST 


LPSTR 
LPTEXTMETRIC 


LPVOID 
LPWNDCLASS 


NEAR 


NPSTR 
PINT 
PSTR 
PWORD 


short 


Definition 


Long pointer to a LOGPEN data struc- 
ture. 


Long pointer to a MEASURE- 
ITEMSTRUCT data structure. 


Long pointer toa METAFILEPICT 
data structure. 


Long pointer to a MSG data structure. 


Long pointer to an OFSTRUCT data 
structure. 


Long pointer to a PAINTSTRUCT 
data structure. 


Long pointer to a PALETTEENTRY 
data structure. 


Long pointer to a POINT data structure. 
Long pointer to a RECT data structure. 


Long pointer to one or more 
RESOURCESTRUCT data structures. 


Long pointer to a character string. 


Long pointer to a TEXTMETRIC data 
structure. 


Long pointer to an undefined data type. 


Long pointer to a WNDCLASS data 
structure. 


Data-type attribute that can be used to 
create a short pointer. 


Near pointer to a character string. 
Pointer to a signed 16-bit integer. 
Pointer to a character string. 

Pointer to an unsigned 16-bit integer. 


Signed 16-bit integer. 
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Type Definition 

void Empty value. It is used with a function 
to specify no return value. 

WORD Unsigned 16-bit integer. 


7.2 Data Structures 


This section lists data structures that are used by Windows. The data structures 
are presented in alphabetical order. The structure definition is given, followed by 
a description of each field. 


BITMAP 


BITMAP 


Bitmap Data Structure 


The BITMAP structure defines the height, width, color format, and bit values of a logical 


bitmap. 


typedef struct tagBITMAP { 


short 
short 
short 
short 
BYTE 
BYTE 
LPSTR 
} BITMAP; 


bmType; 
bmWidth; 
bmHeight; 
bmWidthBytes; 
bmPlanes; 
bmBitsPixel; 
bmBits; 


The BITMAP structure has the following fields: 


Field Description 

bmType Specifies the bitmap type. For logical bitmaps, the bmType field 
must be zero. 

bm Width Specifies the width of the bitmap (in pixels). The width must be 
greater than zero. 

bmHeight Specifies the height of the bitmap (in raster lines). The height 
must be greater than zero. 

bm WidthBytes Specifies the number of bytes in each raster line. This value 
must be an even number since the graphics device interface 
(GDI) assumes that the bit values of a bitmap form an array of 
integer (two-byte) values. In other words, bn WidthBytes x 8 
must be the next multiple of 16 greater than or equal to the 
bmWidth field. 

bmPlanes Points to the number of color planes in the bitmap. 

bmBitsPixel Points to the number of adjacent color bits on each plane needed 
to define a pixel. 

bmBits Points to the location of the bit values for the bitmap. The 
bmBits field must be a long pointer to an array of character (one- 
byte) values. 

Comments - The currently used bitmap formats are monochrome and color. The monochrome bitmap 


uses a one-bit, one-plane format. Each scan is a multiple of 16 bits. 
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Scans are organized as follows for a monochrome bitmap of height n: 
Scan @ 
Scan 1 
Scan nee 
Scan n-1 
The pixels on a monochrome device are either black or white. If the corresponding bit in 
the bitmap is 1, the pixel is turned on (white); if the corresponding bit in the bitmap is 
zero, the pixel is turned off (black). 
All devices that have the RC_BITBLT bit set in the device capabilities support bitmaps. 
Each device has its own unique color format. In order to transfer a bitmap from one device 
to another, use GetDIBits and SetDIBits. 

See Also The CreateBitmapIndirect and GetObject functions in Chapter 4, “Functions Directory,” 


in Reference, Volume 1. 
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Device-Independent Bitmap Format Information 


The BITMAPCOREHEADER structure contains information about the dimensions and 
color format of a device-independent bitmap that is compatible with Microsoft OS/2 Pre- 
sentation Manager versions 1.1 and 1.2 bitmaps. 


typedef struct tagBITMAPCOREHEADER { 
DWORD bcSize; 
WORD bcWidth; 
WORD bcHeight; 
WORD bcPlanes; 
WORD bcBitCount; 
} BITMAPCOREHEADER; 


The BITMAPCOREHEADER structure has the following fields: 


Field Description 

bceSize Specifies the number of bytes required by the BITMAP- 
COREHEADER structure. 

beWidth Specifies the width of the bitmap in pixels. 


bcHeight Specifies the height of the bitmap in pixels. 
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Comments 


Field Description 

bcPlanes Specifies the number of planes for the target device and must be set 
to 1. 

bcBitCount Specifies the number of bits per pixel. This value must be 1, 4, 8, or 
24. 


The BITMAPCOREINFO data structure combines the BITMAPCOREHEADER struc- 
ture and a color table to provide a complete definition of the dimensions and colors of a 
device-independent bitmap. See the description of the BBTMAPCOREINFO data struc- 
ture for more information about specifying a device-independent bitmap. 


An application should use the information stored in the beSize field to locate the color 
table ina BITMAPCOREINFO data structure with a method such as the following: 


pColor = ((LPSTR) pBitmapCoreInfo + (WORD) (pBitmapCorelInfo -> bcSize)) 
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Device-Indpendent Bitmap Information 


Comments 


The BITMAPCOREINFO structure fully defines the dimensions and color information 
for a device-independent bitmap that is compatible with Microsoft OS/2 Presentation 
Manager versions 1.1 and 1.2 bitmaps. 


typedef struct _BITMAPCOREINFO { 
BITMAPCOREHEADER bmciHeader; 
RGBTRIPLE bmciColors[]; 
} BITMAPCOREINFO; 


The BITMAPCOREINFO structure contains the following fields: 


Field Description 


bmciHeader Specifies a BITMAPCOREHEADER data structure that.contains 
information about the dimensions and color format of a device-inde- 
pendent bitmap. 


bmciColors Specifies an array of RGBTRIPLE data structures that define the 
colors in the bitmap. 


An OS/2 Presentation Manager device-independent bitmap consists of two distinct parts: 
a BITMAPCOREINFO data structure that describes the dimensions and colors of the bit- 
map, and an array of bytes which define the pixels of the bitmap. The bits in the array are 
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packed together, but each scan line must be zero-padded to end on a LONG boundary. Seg- 
ment boundaries can appear anywhere in the bitmap, however. The origin of the bitmap is 
the lower-left corner. 


The bcBitCount field of the BITMAPCOREHEADER structure determines the number 
of bits which define each pixel and the maximum number of colors in the bitmap. This 
field may be set to any of the following values: 


Value Meaning 


l The bitmap is monochrome, and the bmciColors field must contain two 
entries. Each bit in the bitmap array represents a pixel. If the bit is clear, 
the pixel is displayed with the color of the first entry in the bmciColors 
table; if the bit is set, the pixel has the color of the second entry in the 
table. 


4 The bitmap has a maximum of 16 colors, and the bmciColors field con- 
tains 16 entries. Each pixel in the bitmap is represented by a four-bit 
index into the color table. 


For example, if the first byte in the bitmap is Ox1F, then the byte repre- 
sents two pixels. The first pixel contains the color in the second table 
entry, and the second pixel contains the color in the 1 6th table entry. 


8 The bitmap has a maximum of 256 colors, and the bmciColors field 
contains 256 entries. In this case, each byte in the array represents a 
single pixel. 


24 The bitmap has a maximum of 2” colors. The bmciColors field is 
NULL, and each three bytes in the bitmap array represents the relative 
intensities of red, green, and blue, respectively, of a pixel. 


The colors in the bmciColors table should appear in order of importance. 


Alternatively, for functions that use device-independent bitmaps, the bmciColors field can 
be an array of 16-bit unsigned integers that specify an index into the currently realized logi- 
cal palette instead of explicit RGB values. In this case, an application using the bitmap 
must call device-independent bitmap functions with the wUsage parameter set to 
DIB_PAL_COLORS. 
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Note The bmciColors field should not contain palette indexes if the bitmap is to be stored ina file or 
transferred to another application. Unless the application uses the bitmap exclusively and under its 
complete control, the bitmap color table should contain explicit RGB values. 


BITMAPFILEHEADER 
Bitmap File Information 


The BITMAPFILEHEADER data structure contains information about the type, size, 
and layout of a device-independent bitmap (DIB) file. 


typedef struct tagBITMAPFILEHEADER { 
WORD bfType; 
DWORD bfSize; 
WORD bfReservedl; 
WORD bfReserved2; 
DWORD bfOfFfBits; 
} BITMAPFILEHEADER; 


The BITMAPFILEHEADER data structure contains the followin g fields: 


Field Description 

bfType Specifies the type of file. It must be BM. 

bfSize Specifies the size in DWORDs of the file. 

bfReserved1 Is reserved and must be set to zero. 

bfReserved2 Is reserved and must be set to zero. 

bfOffBits Specifies in bytes the offset from the BITMAPFILEHEADER 


of the actual bitmap in the file. 


Comments A BITMAPINFO or BITMAPCOREINFO data structure immediately follows the 
BITMAPFILEHEADER structure in the DIB file. 


BITMAPINFO 
Device-Indpendent Bitmap Information 


The BITMAPINFO structure fully defines the dimensions and color information for a 
Windows 3.0 device-independent bitmap. 
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typedef struct tagBITMAPINFO { 
BITMAPINFOHEADER bmiHeader; 
RGBQUAD bmiColors[1]; 
} BITMAPINFO; 
The BITMAPINFO structure contains the following fields: 
Field Description 
bmiHeader Specifies a BITMAPINFOHEADER data structure that con- 
tains information about the dimensions and color format of a 
device-independent bitmap. 
bmiColors Specifies an array of RGBQUAD data structures that define the 
colors in the bitmap. 
Comments A Windows 3.0 device-independent bitmap consists of two distinct parts: a BITMAP- 


INFO data structure that describes the dimensions and colors of the bitmap, and an array 
of bytes that define the pixels of the bitmap. The bits in the array are packed together, but 
each scan line must be zero-padded to end on a LONG boundary. Segment boundaries can 
appear anywhere in the bitmap, however. The origin of the bitmap is the lower-left corner. 


The biBitCount field of the BITMAPINFOHEADER structure determines the number 
of bits which define each pixel and the maximum number of colors in the bitmap. This 
field may be set to any of the following values: 


Value Meaning 


1 The bitmap is monochrome, and the bmiColors field must contain 
two entries. Each bit in the bitmap array represents a pixel. If the bit 
is clear, the pixel is displayed with the color of the first entry in the 
bmiColors table; if the bit is set, the pixel has the color of the second 
entry in the table. 


4 The bitmap has a maximum of 16 colors, and the bmiColors field 
contains up to 16 entries. Each pixel in the bitmap is represented by a 
four-bit index into the color table. 


For example, if the first byte in the bitmap is Ox1F, then the byte rep- 
resents two pixels. The first pixel contains the color in the second 
table entry, and the second pixel contains the color in the 16th table 
entry. 


8 The bitmap has a maximum of 256 colors, and the bmiColors field 
contains up to 256 entries. In this case, each byte in the array repre- 
sents a single pixel. 
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Value | Meaning 


24 The bitmap has a maximum of 274 colors. The bmiColors field is 
NULL, and each three bytes in the bitmap array represents the rela- 
tive intensities of red, green, and blue, respectively, of a pixel. 


The biClrUsed field of the BITMAPINFOHEADER structure specifies the number of 
color indexes in the color table actually used by the bitmap. If the biClrUsed field is set to . 
0, the bitmap uses the maximum number of colors corresponding to the value of the biBit- 
Count field. 


The colors in the bmiColors table should appear in order of importance. 


Alternatively, for functions that use device-independent bitmaps, the bmiColors field can 
be an array of 16-bit unsigned integers that specify an index into the currently realized logi- 
cal palette instead of explicit RGB values. In this case, an application using the bitmap 
must call device-independent bitmap functions with the wUsage parameter set to 
DIB_PAL_COLORS. 


Note The bmiColors field should not contain palette indices if the bitmap is to be stored in a file or 
transferred to another application. Unless the application uses the bitmap exclusively and under its 
complete control, the bitmap color table should contain explicit RGB values. 


BITMAPINFOHEADER 


~ Device-Independent Bitmap Format Information 


The BITMAPINFOHEADER structure contains information about the dimensions and 
color format of a Windows 3.0 device-independent bitmap. 


typedef struct tagBITMAPINFOHEADER{ 
DWORD biSize; 
DWORD biWidth; 
DWORD biHeight; 
WORD biPlanes; 
WORD biBitCount 
DWORD biCompression; 
DWORD biSizelmage; 
DWORD bixPelsPerMeter; 
DWORD biYPelsPerMeter; 
DWORD biClrUsed; 
DWORD biClrImportant; 
} BITMAPINFOHEADER; 


The BITMAPINFOHEADER structure has the following fields: 
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BITMAPINFOHEADER 


Field 
biSize 


biWidth 
biHeight 


biPlanes 
biBitCount 


biCompression 


biSizeImage 


biXPelsPerMeter 


biY PelsPerMeter 


Description 


Specifies the number of bytes required by the BITMAP- 
INFOHEADER structure. 


Specifies the width of the bitmap in pixels. 
Specifies the height of the bitmap in pixels. 


Specifies the number of planes for the target device and 
must be set to 1. 


Specifies the number of bits per pixel. This value must be 
1, 4, 8, or 24. 


Specifies the type of compression for a compressed bit- 
map. It can be one of the following values: 


Value Meaning 

BI_RGB Specifies that the bitmap is not com- 
_ pressed. ° 

BI_RLE8 Specifies a run-length encoded for- 


mat for bitmaps with 8 bits per pixel. 
The compression format is a two- 
byte format consisting of a count byte 
followed by a byte containing a color 
index. See the following “Com- 
ments” section for more information. 


BI_RLE4 Specifies a run-length encoded for- 
mat for bitmaps with 4 bits per pixel. 
The compression format is a two- 
byte format consisting of a count byte 
followed by two word-length color in- 
dexes. See the following 
“Comments” section for more infor- 
mation. 


Specifies the size in bytes of the image. 


Specifies the horizontal resolution in pixels per meter of 
the target device for the bitmap. An application can use this 
value to select a bitmap from a resource group that best 
matches the characteristics of the current device. 


Specifies the vertical resolution in pixels per meter of the 
target device for the bitmap. 
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Comments 


Field Description 


biClrUsed _ Specifies the number of color indexes in the color table ac- 
tually used by the bitmap. If this value is 0, the bitmap uses 
the maximum number of colors corresponding to the value 
of the biBitCount field. See the description of the 
BITMAPINFO data structure earlier in this chapter for 
more information on the maximum sizes of the color table. 


If biClrUsed is nonzero, then the biClIrUsed field speci- 
fies the actual number of colors which the graphics engine 
or device driver will access if the biBitCount field is less 
than 24. If the biBitCount field is set to 24, the biClrUsed 
field specifies the size of the reference color table used to 
optimize performance of Windows color palettes. 


If the bitmap is a “packed” bitmap (that is, a bitmap in 
which the bitmap array immediately follows the BITMAP- 
INFO header and which is referenced by a single pointer), 
the biClrUsed field must be set to 0 or to the actual size of 
the color table. 


biClIrImportant Specifies the number of color indexes that are considered 
important for displaying the bitmap. If this value is 0, then 
all colors are important. 


The BITMAPINFO data structure combines the BITMAPINFOHEADER structure and 
a color table to provide a complete definition of the dimensions and colors of a Windows 
3.0 device-independent bitmap. See the description of the BITMAPINFO data structure 
for more information about specifying a Windows 3.0 device-independent bitmap. 


An application should use the information stored in the biSize field to locate the color 
table ina BITMAPINFO data structure with a method such as the following: 


pColor = ((LPSTR) pBitmapInfo + (WORD) (pBitmapInfo -> biSize)) 


Bitmap Compression Formats 


Windows supports formats for compressing bitmaps that define their colors with 8 bits per 
pixel and with 4 bits per pixel. Compression reduces the disk and memory storage required 
for the bitmap. The following paragraphs describe these formats. 


When the biCompression field is set to BI_LRLE8, the bitmap is compressed using a run- 
length encoding format for an 8-bit bitmap. This format may be compressed in either of 
two modes: 
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= Encoded 


= Absolute 


Both modes can occur anywhere throughout a single bitmap. 


Encoded mode consists of two bytes: the first byte specifies the number of consecutive 
pixels to be drawn using the color index contained in the second byte. In addition, the first 
byte of the pair can be set to zero to indicate an escape that denotes an end of line, end of 
bitmap, or a delta. The interpretation of the escape depends on the value of the second byte 
of the pair. The following list shows the meaning of the second byte: 


Second Byte 

Of Escape Meaning 

0 End of line. 

1 End of bitmap. 

2 Delta. The two bytes following the escape contain unsigned values in- 


dicating the horizontal and vertical offset of the next pixel from the 
current position. 


Absolute mode is signalled by the first byte set to zero and the second byte set to a value 
between 03H and FFH. In absolute mode, the second byte represents the number of bytes 
which follow, each of which contains the color index of a single pixel. When the second 
byte is set to 2 or less, the escape has the same meaning as in encoded mode. In absolute 
mode, each run must be aligned on a word boundary. 


The following example shows the hexadecimal values of an 8-bit compressed bitmap: 


93 04 O5 86 BB G3 45 56 67 BB B2 78 BB O2 O5 G1 
G2 78 02 OG 99 1E 2B Bl 


This bitmap would expand as follows (two-digit values represent a color index for a single 
pixel): 


94 04 04 

G6 06 86 B6 06 

45 56 67 

78 78 

move current position 5 right and 1 down 
78 78 

end of line 

LE LE LE LE: TE TEs LET ae 

end of RLE bitmap 
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When the biCompression field is set to BI_LRLE4, the bitmap is compressed using a run- 
length encoding format for a 4-bit bitmap, which.also uses encoded and absolute modes. In 
encoded mode, the first byte of the pair contains the number of pixels to be drawn using 
the color indexes in the second byte. The second byte contains two color indexes, one in its 
high-order nibble (that is, its low-order four bits) and one in its low-order nibble. The first 
of the pixels is drawn using the color specified by the high-order nibble, the second is 
drawn using the color in the low-order nibble, the third is drawn with the color in the high- 
order nibble, and so on, until all the pixels specified by the first byte have been drawn. 


In absolute mode, the first byte contains zero, the second byte contains the number of color 
indexes that follow, and subsequent bytes contain color indexes in their high- and low- 
order nibbles, one color index for each pixel. In absolute mode, each run must be aligned 
on a word boundary. The end-of-line, end-of-bitmap, and delta escapes also apply to 
BI_RLE4. 


The following example shows the hexadecimal values of a 4-bit compressed bitmap: 


03 04 05 B6 BB G6 45 56 67 BB B4 78 BB B2 B5 B1 
G4 78 0B OB B9 1E BB Bl 


This bitmap would expand as follows (single-digit values represent a color index for a 


single pixel): 
i) 
G6 @ 
5667 
7 


CLIENTCREATESTRUCT 
MDI Client Window Creation Structure 


The CLIENTCREATESTRUCT data structure contains information about the menu and 
first multiple document interface (MDI) child window of an MDI client window. An appli- 
cation passes a long pointer to this structure as the /pParam parameter of the Create Win- 
dow function when creating an MDI client window. 


typedef struct tagCLIENTCREATESTRUCT 
{ 
HMENU hWindowMenu; 
WORD idFirstChild; 
} CLIENTCREATESTRUCT; 


The CLIENTCREATESTRUCT structure contains the following fields: 
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Field Description 


hWindowMenu Is the menu handle of the application’s Window menu. An appli- 
cation can retrieve this handle from the MDI frame window’s 
menu using the GetSubMenu function. 


idFirstChild Is the child window ID of the first MDI child window created. 
Windows increments the ID for each additional MDI child 
window that the application creates, and reassigns identifiers 
when the application destroys a window to keep the range of 
identifiers continuous. These identifiers are used in WM_COM- 
MAND messages to the application’s MDI frame window when 
a child window is selected from the Window menu, and should 
not conflict with any other command identifiers. 


COLORREF 
Color Specification 


A COLORREF color value is a long integer that specifies a color. GDI functions that re- 
quire a color (such as CreatePen and FloodFill) accept a COLORREF value as a para- 
meter. Depending on how an application uses the COLORREF value, the value has three 
distinct forms. It may specify any of the following: 

= Explicit values for red, green, and blue (RGB) 


m= An index into a logical color palette 


= A palette-relative RGB value 


Explict RGB When specifying an explicit RGB value, the COLORREF value has the following hex- 
adecimal form: 


@x@0bbggrr 


The low-order byte contains a value for the relative intensity of red; the second byte con- 
tains a value for green, and the third byte contains a value for blue. The high-order byte 
must be zero. The maximum value for a single byte is FF (hexadecimal). The following list 
illustrates the hexadecimal values that produce the indicated colors. 


Value Color 


OxO000000FF Pure red 
OxO0000FFOO Pure green 
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Value Color 
OxO00FFO000 Pure blue 
0x00000000 Black 
OxOOFFFFFF White 
0x00808080 Medium gray 


The RGB macro accepts values for red, green, and blue, and returns an explicit RGB 
COLORREF value. 


Palette Index When specifying an index into a logical color palette, the COLORREF value has the fol- 
lowing hexadecimal form: 


OxB19B0i1i74 


The two low-order bytes consist of a 16-bit integer specifying an index into a logical 
palette. The third byte is not used and must be zero. The fourth (high-order) byte must be 
set to 1. 


For example, the hexadecimal value 0x01000000 specifies the color in the palette entry of 
index 0; 0x0100000C specifies the color in the entry of index 12, and so on. 


The PALETTEINDEX macro accepts an integer representing an index into a logical 
palette and returns a palette-index COLORREF value. 


Palette-Relative RGB 


When specifying a palette-relative RGB value, the COLORREF value has the following 
hexadecimal form: 


OxO@2bbggrr 


As with an explicit RGB, the three low-order bytes contain values for red, green, and blue; 
the high-order byte must be set to 2. . 


For output devices that support logical palettes, Windows matches a palette-relative RGB 
value to the nearest color in the logical palette of the device context, as though the applica- 
tion had specified an index to that palette entry. If an output device does not support a sys- 
tem palette, then Windows uses the palette-relative RGB as though it were an explict RGB 
COLORREF value. 


The PALETTERGB macro accepts values for red, green, and blue, and returns a palette- 
relative RGB COLORREF value. 


Comments Before passing a palette-index or palette-relative RGB COLORREF value to a function 
that also requires a device-context parameter, an application that uses its own palette must 


7-19 COMPAREITEMSTRUCT 


select its palette into the device context (by calling the SelectPalette function) and realize 
the palette (by calling RealizePalette). This ensures that the function will use the correct 
palette-entry color. For functions that create an object (such as CreatePen), the application 
must select and realize the palette before selecting the object for the device context. 


COMPAREITEMSTRUCT 


Owner-Draw Item-Sorting Information 


The COMPAREITEMSTRUCT structure supplies the identifiers and application-sup- 
plied data for two items in a sorted owner-draw combo box or list box. 


Whenever an application adds a new item to an owner-draw combo or list box created with 
the CBS_SORT or LBS_SORT style, Windows sends the owner a WM_COMPAREITEM 
message. The /Param parameter of the message contains a long pointer to a COMPARE- 
ITEMSTRUCT data structure. When the owner receives the message, the owner com- 
pares the two items and retums a value indicating which item sorts before the other. For 
more information, see the description of the WM_COMPAREITEM message in Chapter 6, 
“Messages Directory,” in Reference, Volume 1. 


typedef struct tagCOMPAREITEMSTRUCT { 
WORD CtiType; 
WORD CtlID; 
HWND hwndItem; 
WORD itemID1; 
DWORD itemDatal; 
WORD jtemID2; 
DWORD itemData2; 
} COMPAREITEMSTRUCT; 


The COMPAREITEMSTRUCT structure has the following fields: 


Field Description 

CtlType Is ODT_LISTBOX (which specifies an owner-draw list box) or 
ODT_COMBOBOXxX (which specifies an owner-draw combo box). 

CtlID Is the control ID for the list box or combo box. 

hwndItem Is the window handle of the control. 

itemID1 Is the index of the first item in the list box or combo box being com- 

pared. 
itemDatal Is application-supplied data for the first item being compared. This 


value was passed as the /Param parameter of the message that added 
the item to the combo or list box. 
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Field Description 

itemID2 Is the index of the second item in the list box or combo box being 
compared. 

itemData2 Is application-supplied data for the second item being compared. 


This value was passed as the /Param parameter of the message that 
added the item to the combo or list box. » 


COMSTAT 


Communication-Device Status 
The COMSTAT structure contains information about a communications device. 


typedef struct tagCOMSTAT { 
BYTE fCtsHold: 1; 
BYTE fDsrHold: 1; 
BYTE fRISdHold: 1 
BYTE fXoffHold: 1 
BYTE fXoffSent: 1 
BYTE fEof: 1; 
BYTE fTxim: 1; 
WORD cbInQue; 
WORD cbOutQue; 

} COMSTAT; 


The COMSTAT structure has the following fields: 


Field Description 

fCtsHold: 1 Specifies whether transmission is waiting for the clear-to-send 
(CTS) signal to be sent. 

fDsrHold: 1 Specifies whether transmission is waiting for the data-set-ready 
(DSR) signal to be sent. 

fRisdHold: 1 Specifies whether transmission is waiting for the receive-line- 


signal-detect (RLSD) signal to be sent. 


fXoffHold: 1 Specifies whether transmission is waiting as a result of the Xoff- 
Char character being received. 


fXoffSent: 1 Specifies whether transmission is waiting as a result of the Xoff- 
Char character being transmitted. Transmission halts when the 
XoffChar character is transmitted and used by systems that take 
the next character as XON, regardless of the actual character. 
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Field Description 

fEof: 1 . Specifies whether the EofChar character has been received. 

fTxim: 1, Specifies whether a character is waiting to be transmitted. 

cbInQue Specifies the number of characters in the receive queue. 

cbOutQue Specifies the number of characters in the transmit queue. 
See Also The GetCommError function in Chapter 4, “Functions Directory,” in Reference, 

Volume 1. 
CREATESTRUCT 


Window-Creation Structure 


The CREATESTRUCT structure defines the initialization parameters passed to an appli- 
cation’s window function. 


typedef struct tagCREATESTRUCT { 
LPSTR  JIpCreateParams; 
HANDLE hInstance; 
HANDLE hMenu; 
HWND hwndParent; 


int Cy; 
int CX; 
int y3 
int xX; 


long style; 
LPSTR lpszName; 
LPSTR  IpszClass; 
long ExStyle; 

} CREATESTRUCT; 


The CREATESTRUCT structure has the following fields: 


Field Description 
IpCreateParams Points to data to be used for creating the window. 
hInstance Identifies the module-instance handle of the module that owns 


the new window. 


hMenu Identifies the menu to be used by the new window. 


DCB 
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Field 


hwndParent 


cy 


cx 


Mi 


style 


IpszName 


IpszClass 


ExStyle 


DCB 


Communications-Device Control Block 


Description 


Identifies the window that owns the new window. This field is 
NULL if the new window is a top-level window. 


Specifies the height of the new window. 
Specifies the width of the new window. 


Specifies the y-coordinate of the upper-left corner of the new 
window. Coordinates are relative to the parent window if the 
new window is a child window. Otherwise, the coordinates are 
relative to the screen origin. 


Specifies the x-coordinate of the upper-left corner of the new 
window. Coordinates are relative to the parent window if the 
new window is a child window. Otherwise, the coordinates are 
relative to the screen origin. 


Specifies the new window’s style. 


Points to a null-terminated character string that specifies the new 
window’s name. 


Points to a null-terminated character string that specifies the new 
window’s class name. 


Specifies extended style for the new window. 


The DCB structure defines the control setting for a serial communications device. 


typedef struct tagDCB { 


BYTE Id; 

WORD BaudRate; 
BYTE ByteSize; 
BYTE Parity; 
BYTE StopBits; 
WORD R1lsTimeout; 
WORD CtsTimeout; 
WORD DsrTimeout; 


BYTE fBinary: 1; 


BYTE fRtsDisable: 


BYVLE (Parity: 2s 


i 


BYTE fOutxCtsFlow: 1; 
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BYTE fOutxDsrFlow: 1; 
BYTE fDummy: 2; 
BYTE fDtrDisable: 1; 


BYTE fOutxX: 1; 
BYTE fiInxX: 1; 
BYTE fPeChar: 1; 
BYTE fNull: 1; 
BYTE fChEvt: 1; 
BYTE fDtrFlow: 1; 
BYTE fRtsFlow: 1; 
BYTE fDummy2: 1; 


char XonChar; 
char XoffChar; 
WORD XonLim; 
WORD XoffLim; 
char PeChar; 
char EofChar; 
char EvtChar; 
WORD TxDelay; 
} DCB; 


The DCB structure has the following fields: 


Field Description 


Id Specifies the communication device. This value is set by the 
device driver. If the most significant bit is set, then the DCB 
structure is for a parallel device. 


BaudRate Specifies the baud rate at which the communications device 
operates. 


ByteSize Specifies the number of bits in the characters transmitted and 
received. The ByteSize field can be any number from 4 to 8. 


Parity Specifies the parity scheme to be used. The Parity field can 
be any one of the following values: 


Value . Meaning 
EVENPARITY Even 
MARKPARITY Mark 
NOPARITY No parity 
ODDPARITY Odd 


DCB 


Field 


StopBits 


RisTimeout 


CtsTimeout 
DsrTimeout 


fBinary: 1 


fRtsDisable: 1 


fParity: 1 


fOutxCtsFlow: 1 


fOutxDsrF low: 1 


fDummy: 2 
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Description 
Value Meaning 
SPACEPARITY Space 


Specifies the number of stop bits to be used. The StopBits 
field can be any one of the following values: 


Value | Meaning 
ONESTOPBIT 1 stop bit 
ONESSTOPBITS 1.5 stop bits 
TWOSTOPBITS 2 stop bits 


Specifies the maximum amount of time (in milliseconds) the 
device should wait for the receive-line-signal-detect (RLSD) 
signal. (RLSD is also known as the carrier detect (CD) signal.) 


Specifies the maximum amount of time (in milliseconds) the 
device should wait for the clear-to-send (CTS) signal. 


Specifies the maximum amount of time (in milliseconds) the 
device should wait for the data-set-ready (DSR) signal. 


Specifies binary mode. In nonbinary mode, the EofChar 
character is recognized on input and remembered as the end of 
data. 


Specifies whether or not the request-to-send (RTS) signal is 
disabled. If the fRtsDisable field is set, RTS is not used and re- 
mains low. If fRtsDisable is clear, RTS is sent when the 

device is opened and turned off when the device is closed. 


Specifies whether parity checking is enabled. If the fParity 
field is set, parity checking is performed and errors are re- 
ported. 


Specifies that clear-to-send (CTS) signal is to be monitored 
for output flow control. If the fOutxCtsFlow field is set and 
CTS is turned off, output is suspended until CTS is again sent. 


_ Specifies that the data-set-ready (DSR) signal is to be moni- 


tored for output flow control. If the fOutxDsrFlow field is set 
and DSR is turned off, output is suspended until DSR is again 
sent. 


Reserved. 
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DCB 


Field 
fDtrDisable: 1 


fOutX: 1 


fInX: 1 


fPeChar: 1 


fNull: 1 
fChEvt: 1 


fDtrFlow: 1 


fRtsFlow: 1 


fdummy2: 1 
XonChar 


XoffChar 


XonLim 


Description 


Specifies whether the data-terminal-ready (DTR) signal is dis- 
abled. If the fDtrDisable field is set, DTR is not used and 
remains low. If fDtrDisable is clear, DTR is sent when the 
device is opened and turned off when the device is closed. 


Specifies that XON/XOFF flow control is used during trans- 
mission. If the fOutX field is set, transmission stops when the 
XoffChar character is received, and starts again when the 
XonChar character is received. 


Specifies that XON/XOFF flow control is used during recep- 
tion. If the fInX field is set, the XonChar character is sent 
when the receive queue comes within XoffLim characters of 
being full, and the XonChar character is sent when the re- 
ceive queue comes within XonLim characters of being empty. 


Specifies that characters received with parity errors are to be 
replaced with the character specified by the fPeChar field. 
The fParity field must be set for the replacement to occur. 


Specifies that received null characters are to be discarded. 


Specifies that reception of the EvtChar character is to be 


- flagged as an event. 


Specifies that the data-terminal-ready (DTR) signal is to be 
used for receive flow control. If the fDtrFlow field is set, 
DTR is turned off when the receive queue comes within Xof- 
fLim characters of being full, and sent when the receive queue 
comes within XonLim characters of being empty. 


Specifies that the ready-to-send (RTS) signal is to be used for 
receive flow control. If the fRtsFlow field is set, RTS is 
turned off when the receive queue comes within XoffLim 
characters of being full, and sent when the receive queue 
comes within XonLim characters of being empty. 


Reserved. 


Specifies the value of the XON character for both transmis- 
sion and reception. 


Specifies the value of the XOFF character for both transmis- 
sion and reception. 


Specifies the minimum number of characters allowed in the re- 
ceive queue before the XON character is sent. 
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See Also 


Field Description 


XoffLim Specifies the maximum number of characters allowed in the 
receive queue before the XOFF character is sent. The Xoff- 
Lim value is subtracted from the size of the receive queue (in 
bytes) to calculate the maximum number of characters al- 


lowed. 

PeChar Specifies the value of the character used to replace characters 
received with a parity error. - 

EofChar Specifies the value of the character used to signal the end of 
data. 

EvtChar Specifies the value of the character used to signal an event. . 

TxDelay Not currently used. 


The BuildCommDCB, GetCommState, and SetCommState functions in Chapter 4, 
“Functions Directory,” in Reference, Volume 1. 


DELETEITEMSTRUCT 


Deleted Owner-Draw List-Box Item 


The DELETEITEMSTRUCT structure describes a deleted owner-draw list-box or 
combo-box item. When an item is removed from the list box or combo box, or when the 
list box or combo box is destroyed, Windows sends the WM_DELETEITEM message to 
the owner for each deleted item; the /Param parameter of the message contains a pointer to 
this structure. 


typedef struct tagDELETEITEMSTRUCT 
{ 


WORD CtlType 

WORD CtlI1D; 

WORD itemID; 

HWND hwndItem; 

DWORD itemData; 
} DELETEITEMSTRUCT; 


The DELETEITEMSTRUCT structure has the following fields: 
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DEVMODE 


Field 
CtlType 


CtlID 
itemID 


hwndItem 


itemData 


DEVMODE 


Description 


Is ODT_LISTBOX (which specifies an owner-draw list box) or 
ODT_COMBOBOxX (which specifies an owner-draw combo 
box). 


Is the control ID for the list box or combo box. 


Is the index of the item in the list box or combo box being re- 
moved. 


Is the window handle of the control. 


Contains the value passed to the control in the /Param parameter 
of the LB_LINSERTSTRING, LB_ADDSTRING, CB_INSERT- 
STRING, or CB_ADDSTRING message when the item was 
added to the list box. 


Printer Driver Initialization Information 


The DEVMODE data structure contains information about the device initialization and en- 
vironment of a printer driver. An application passes mus structure to the DeviceCapabili- 
ties and ExtDeviceMode functions. 


typedef struct _devicemode { 


char dmDeviceName[32]; 
WORD dmSpecVersion; 
WORD dmDriverVersion; 
WORD dmSize; 

WORD dmDriverExtra; 
DWORD dmFields; 

short dmOrientation; 
short dmPaperSize; 
short dmPaperLength; 
short  dmPaperWidth; 
short dmScale; 

short dmCopies; 

short dmDefaultSource; 
short dmPrintQuality; 
short dmColor; 

Short dmDuplex; 

BYTE dmDriverData[LdmDriverExtra]; 
} DEVMODE; 


The DEVMODE structure contains the following fields: 


DEVMODE 
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Field 


dmDeviceName 


dmSpecVersion 


dmDriver Version 


dmSize 


dmDriverExtra 


dmFields 


dmOrientation 


dmPaperSize 


Description 


Specifies the name of the device the driver supports; for 
example, “PCL/HP LaserJet” in the case of PCL/HP® 
LaserJet®. This string is unique among device drivers. 


Specifies the version number of the initialization data 
specification upon which the structure is based. The ver- 
sion number follows the Windows version number and is 
currently 0x300. 


Specifies the printer driver version number assigned by the 
printer driver developer. 


Specifies the size in bytes of the DEVMODE structure 
except the dmDriverData (device-specific) field. If an 
application manipulates only the driver-independent por- 
tion of the data, it can use this field to determine the length 
of the structure without having to account for different ver- 
sions. 


Contains the size of the dmDriverData field and is the 
length of the device-specific data in the DEVMODE 
structure. If an application does not use device-specific 
information, it should set this field to zero. 


Is a bitfield that specifies which of the remaining fields in 
the DEVMODE structure have been initialized. Bit 0 
(defined as DM_ORIENTATION) corresponds to 
dmOrientation; bit 1 (defined as DM_PAPERSIZE) 
specifies dmPaperSize, and so on. A printer driver sup- 
ports only those fields that are appropriate for the printer 


. technology. 


Selects the orientation of the paper. It can be either 
DMORIENT_PORTRAIT (1) or DMORIENT_LAND- 
SCAPE (2). 


Selects the size of the paper to print on. This field may be 
set to zero if the length and width of the paper are both set 
by the dmPaperLength and dmPaperWidth fields. Other- 
wise, the dmPaperSize field can be set to one of the 
following predefined values: 


Value Meaning 


DMPAPER_LETTER 814-by-11-inch paper 
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Field Description 
Value Meaning 
DMPAPER_LEGAL 814-by-14-inch paper 
DMPAPER_A4 210-by-297-millimeter paper 


DMPAPER_CSHEET 17-by-22-inch paper 
DMPAPER_DSHEET 22-by-34-inch paper 
DMPAPER_ESHEET 34-by-44-inch paper 


DMPAPER_ENV_9 374-by-874-inch #9 envelope 

DMPAPER_ENV_10 4\%-by-914-inch #10 envelope 

DMPAPER_ENV_11 4\4-by-1034-inch #11 
envelope 


DMPAPER_ENV_12 4¥4-by-11-inch #12 envelope 
DMPAPER_ENV_14 5-by-1114-inch #14 envelope 


dmPaperLength Overrides the length of the paper specified by the 
dmPaperSize field, either for custom paper sizes or for 
devices such as dot-matrix printers which can print on a 
page of arbitrary length. These values, along with all other 
values which specify a physical length, are in tenths of a 


millimeter. 

dmPaper Width Overrides the width of the paper specified by the 
dmPaperSize field. 

dmScale Scales the printed output. The apparent page size is scaled 


by a factor of dmScale/100 from the physical page size. A 
letter-size paper with a dmScale value of 50 would appear 
to be 17 by 22 inches, and output text and graphics would 
be correspondingly half their normal height and width. 


dmCopies Selects the number of copies printed if the device supports 
multiple-page copies. 


dmDefaultSource Specifies the paper bin from which the paper is fed by de- 
. fault. The application can override this selection by using 
the GETSETPAPERBINS escape. Possible bins include 
the following: 
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Field Description 


DMBIN_DEFAULT 
DMBIN_UPPER 
DMBIN_LOWER 
DMBIN_MANUAL 
DMBIN_TRACTOR 
DMBIN_ENVELOPE 


There is also a range of values reserved for device-specific 
bins. The GETSETPAPERBINS and ENUMPAPERBINS 
escapes use these indexes to be consistent with initializa- 
tion information. 


dmPrintQuality Specifies the printer resolution. There are four predefined 
device-independent values: 


DMRES_HIGH (-4) 
DMRES_MEDIUM (3) 
DMRES_LOW (-2) 
DMRES_DRAFT (-1) 


If a positive value is given, it specifies the number of dots 
per inch (DPI) and is therefore device dependent. 


dmColor Switches between color and monochrome on color print- 
ers. Possible values are: 


= DMCOLOR_COLOR (1) 
=» DMCOLOR_MONOCHROME (2). 


dmDuplex Selects duplex or double-sided printing for printers capable 
of duplex printing. Values for this field include: 


= DMDUP_SIMPLEX (1) 
=» DMDUP_HORIZONTAL (2) 
= DMDUP_VERTICAL (3). 


dmDriverData[ ] Contains device-specific data defined by the device driver. 


Comments Only drivers fully updated for Windows version 3.0 and which export the ExtDeviceMode 
function use the DEVMODE data structure. 
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DLGTEMPLATE 
Dialog Template 


The DLGTEMPLATE defines the contents of a dialog box. This structure is divided into 
three distinct parts: 


Part Description 

Header Data Contains a general description of the dialog box. 

Structure 

Font-Information Defines the font with which text is drawn in the dialog box. This 
Data Structure part is optional. 

List of Items” Describes the parts that compose the dialog box. 


The CreateDialogIndirect, CreateDialogIndirectParam, DialogBoxIndirect, and Dial- 
ogBoxIndirectParam functions use this structure. 


Header Data Structure 
The DLGTEMPLATE header is shown here: 


typedef struct { 
long dtStyle; 
BYTE dtItemCount; 


int dtx; 
int dty; 
int dtcx; 
int dtCyY; 


char dtMenuName[]; 

char dtClassName[]; 

char dtCaptionText[]; 
} DLGTEMPLATE; 


The DLGTEMPLATE header has the following fields: 


Field Description 


dtStyle Specifies the style of the dialog box. This field may be any or 
all of these values: 
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Field 


Description 


Value 


DS_LOCALEDIT 


DS_SYSMODAL 


DS_MODALFRAME 


DS_ABSALIGN 


DS_SETFONT 


Meaning 


Specifies that text storage for 
edit controls will be allocated in 
the application’s local data seg- 
ment. This allows the use of the 
EM_GETHANDLE and 
EM_SETHANDLE messages. 
If this style is not specified, edit- 
control data is located in a 
separate global data block. 


Specifies a system-modal 
dialog box. 


Specifies a dialog box with a 
modal dialog-box border. This 
style can be combined with the 
WS_CAPTION and WS_SYS- 
MENU style flags to create a 
dialog box with a title bar and 
System menu. 


Indicates that dtX and dtY are 
relative to the screen origin, not 
to the owner of the dialog box. 


Specifies that a font other than 
the system font is to be used to 
draw text in the dialog box. If 
this flag is set, the FONTINFO 
data structure described in the 
following paragraphs must im- 
mediately follow the 
DLGTEMPLATE header. 


When Windows creates a 
dialog box with this attribute, 
Windows sends the WM_SET- 
FONT message to the 
dialog-box window prior to 
creating the controls. 
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Field 


dtItemCount 


dtX 


dtY 


dtCx 


dtCY 


dtMenuName[ ] 


dtClassName[ ] 


dtCaptionText[ ] 
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Description 
Value Meaning 
DS_NOIDLEMSG Specifies that Windows will not 


send the WM_ENTERIDLE 
message to the owner of the 
dialog box while the dialog box 
is displayed. 


Specifies the number of items in the dialog box. A dialog box 
can contain up to 255 controls. 


Specifies the x-coordinate of the upper-left corner of the dialog 
box in units of 4 of the current dialog base width unit. The 
dialog base units are computed from the height and width of 
the current system font; the GetDialogBaseUnits function re- 
turns the current dialog base units in pixels. Unless 
DS_ABSALIGN is set in the dtStyle field, this value is rela- 
tive to the origin of the parent window’s client area. 


Specifies the y-coordinate of the upper-left corner of the dialog 
box in units of 18 of the current dialog base height unit. Unless 
DS_ABSALIGN is set in the dtStyle field, this value is rela- 
tive to the origin of the parent window’s client area. 


Specifies the width of the dialog box in units of 4 of the 
dialog base width unit. 


Specifies the height of the dialog box in units of 8 of the 
dialog base height unit. 


Specifies a null-terminated string that specifies the name of the 
dialog box’s menu. If this field is NULL, the dialog-box 
window does not have a menu. 


Specifies a null-terminated string that supplies the name of the 
dialog box’s class. If dtClassName[ ] is zero, it creates a 
dialog box with the standard dialog-box style. If an application 
specifies a class name, it should provide a dialog procedure 
that processes each dialog-box message directly or calls the 
DefDlgProc function to process the message. Also, the applica- 
tion must register the class with the cbWndExtra field of the 
WNDCLASS data structure set to DLGWINDOWEXTRA. 


Specifies a null-terminated string that supplies the caption for 
the dialog box. 
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Font-Information Data Structure 


Item List 


The FONTINFO data structure contains information about the point size and face name of 
the font which Windows is to use to draw text in the dialog box. 


typedef struct{ 

short int  PointSize;— 

char. szTypeFaceL]; /* A null-terminated string */ 
} FONTINFO; 


The FONTINFO structure has the following fields: 


Field Description 

PointSize Specifies the size of the typeface in points. 

szTypeFace Specifies the name of the typeface; for example, “Courier”. 
Comments 


The font specified must have been previously loaded, either from WIN.INI or explicitly by 
calling the LoadFont function. 


The item list consists of one or more DLGITEMTEMPLATE data structures, one for 

each control in the dialog box. The first such structure immediately follows the FONT- 
INFO structure or the header at the first byte after the terminating null character in the 

szTypeF ace field or the dtCaptionText[ ] field. The following shows the format of the 
DLGITEMTEMPLATE structure. 


typedef struct { 


int dtilXx; 
int dtilY; 
int dtilCx; 
int dtilCY; 
int dtillID; 


long dtilStyle; 
char dtilClass(]; 
char dtilTextl]; 
BYTE dtillnfo; 
PTR dtilData; 

} DLGITEMTEMPLATE 


The DLGITEMTEMPLATE data structure has the following fields: 


Field 
dtilX 


dtilY 


dtilCX 


dtilCy 


dtilID 
dtilStyle 
dtilClass[ J 


dtilText[ ] 
dtillnfo 


dtilData 
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Description 


Specifies the x-coordinate of the upper-left corner of the dialog-box 
item in units of !/ of the current dialog base width unit, relative to 
the origin of the dialog box. The dialog base units are computed from 
the height and width of the current system font. The GetDialog- 
BaseUnits function returns the current dialog base units in pixels. 


Specifies the y-coordinate of the upper-left corner of the dialog-box 
item in units of !/ of the current dialog base height unit. This value is 
relative to the origin of the dialog box. 


Specifies the width-extent of the dialog-box item in units of 1/4 of the 
current dialog base width unit. Dialog base units are computed from 
the height and width of the current system font. The GetDialog- 
BaseUnits function returns the current dialog base units. 


Specifies the height of the dialog-box item in units of 14 of the dialog 
base height unit. 


Specifies the dialog-box item identification number. 
Specifies the style of the dialog-box item. 


A null-terminated string that specifies the control’s class. It may be 
one of the following class names: 


BUTTON 
EDIT 

STATIC 
LISTBOX 
SCROLLBAR 
COMBOBOX 


Specifies the text for the item; it is a null-terminated string. 


Specifies the number of bytes of additional data that follows this item 
description and precedes the next item description. 


Specifies additional data which the CreateWindow function receives 
through the IpCreateParams field of the CREATESTRUCT data 
structure. This field is zero length if dtilInfo is zero. 
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DRAWITEMSTRUCT 
Owner-Draw Control! Drawing Information 


The DRAWITEMSTRUCT structure provides information the owner needs to determine 
how to paint an owner-draw control. The owner of the owner-draw control receives a 
pointer to this structure as the /Param parameter of the WM_DRAWITEM message. 


typedef struct tagDRAWITEMSTRUCT 

{ 
WORD CtlType; 
WORD CtlID; 
WORD itemID; 
WORD jtemAction; 
WORD itemState; 
HWND hwndIitem; 
HDC hDC; 
RECT rcItem; 
DWORD itemData; 

} DRAWITEMSTRUCT; 


The DRAWITEMSTRUCT structure has the following fields: 


Field Description 

CtlType Is the control type. The values for control types are as follows: 
Value Meaning 
ODT_BUTTON Owner-draw button. 
ODT_COMBOBOX Owner-draw combo box. 
ODT_LISTBOX Owner-draw list box. 
ODT_MENU Owner-draw menu. 

CtlID Is the control ID for a combo box, list box or button. This field is 


not used for a menu. 


-itemID Is the menu-item ID for a menu or the index of the item in a list 
box or combo box. For an empty list box or combo box, this field 
can be —1. This allows the application to draw only the focus 
rectangle at the coordinates specified by the rcItem field even 
though there are no items in the control. This indicates to the user 
whether the list box or combo box has input focus. The setting of 
the bits in the itemAction field determines whether the rectangle is 
to be drawn as though the list box or combo box has input focus. 
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Field 


itemAction 


itemState 


hwndItem 


Description 


Defines the drawing action required. This will be one or more of 


the following bits: 


Value 


ODA_DRAWENTIRE 


ODA_FOCUS 


ODA_SELECT 


Description 


This bit is set when the entire con- 
trol needs to be drawn. 


This bit is set when the control 
gains or loses input focus. The item- 
State field should be checked to 
determine whether the control has 
focus. 


This bit is set when only the selec- 
tion status has changed. The 
itemState field should be checked 
to determine the new selection state. 


Specifies the visual state of the item after the current drawing ac- 
tion takes place. That is, if a menu item is to be grayed, the state 
flag ODS_GRAYED will be set. The state flags are: 


Value 


ODS_CHECKED 


ODS_DISABLED 
ODS_FOCUS 


ODS_GRAYED 


ODS_SELECTED 


Description 


This bit is set if the menu item is to 
be checked. This bit is used only in 
a menu. 


This bit is set if the item is to be 
drawn as disabled. 


This bit is set if the item has input 
focus. 


This bit is set if the item is to be 
grayed. This bit is used only ina 
menu. 


This bit is set if the item’s status is 
selected. 


For combo boxes, list boxes and buttons, this field specifies the 
window handle of the control; for menus, it contains the handle of 
the menu (HMENU) containing the item. 
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Field Description 


hDC Identifies a device context; this device context must be used when 
performing drawing operations on the control. 


rcItem Is a rectangle in the device context specified by the hDC field that 
defines the boundaries of the control to be drawn. Windows auto- 
matically clips anything the owner draws in the device context for 
combo boxes, list boxes, and buttons, but does not clip menu items. 
When drawing menu items, the owner must ensure that the owner 
does not draw outside the boundaries of the rectangle defined by 
the rcItem field. 


itemData For a combo box or list box, this field contains the value that was 
passed to the list box in the /Param parameter of one of the the fol- 
lowing messages: 


us CB_ADDSTRING 
a CB_INSERTSTRING 
=» LB_ADDSTRING 
« LB_INSERTSTRING 


For a menu, this field contains the DWORD value passed as the 
IpNewltem parameter of the InsertMenu which inserted the menu 
item. Its contents are undefined for buttons. 


HANDLETABLE 
Window-Handle Table 


The HANDLETABLE structure is an array of handles, each of which identifies a GDI ob- 
ject. 


HANDLE objectHandle[1] 


The HANDLETABLE structure has the following field: 


Field Description 


objectHandle[1] Identifies an array of handles. 
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LOGBRUSH 


Logical-Brush Attribute Information 


The LOGBRUSH structure defines the style, color, and pattern of a physical brush to be 
created by using the CreateBrushIndirect function. 


typedef struct tagLOGBRUSH { 
WORD lbStyle; 
COLORREF 1bColor; 
short int lbHatch;_ 

} LOGBRUSH; 


The LOGBRUSH structure has the following fields: 


Field Description 
IbStyle Specifies the brush style. The IbStyle field can be any one of the following 
styles: 
Style Meaning 
BS_DIBPATTERN Specifies a pattern brush defined by a device-in- 
dependent bitmap (DIB) specification. 
BS_HATCHED Specifies a hatched brush. 
BS_HOLLOW Specifies a hollow brush. 
BS_PATTERN Specifies a pattern brush defined by a memory 
bitmap. 
BS_SOLID Specifies a solid brush. 


IbColor Specifies the color in which the brush is to be drawn. If IbStyle is 
BS_HOLLOW or BS_PATTERN, IbColor is ignored. 


If IpStyle is BS_DIBPATTERN, the low-order word of IbColor specifies 
whether the bmiColors fields of the BITMAPINFO data structure con- 
tain explicit RGB values or indexes into the currently realized logical 
palette. The IbColor field must be one of the following values: 


Value Meaning 


DIB_PAL_ COLORS The color table consists of an array of 16-bit in- 
dexes into the currently realized logical palette. 


DIB_RGB_COLORS The color table contains literal RGB values. 
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Field Description 
IbHatch Specifies a hatch style. The meaning depends on the brush style. 


-. If IbStyle is BS_DIBPATTERN, the IbHatch field contains a handle to a 
' packed DIB. To obtain this handle, an application calls the GlobalAlloc 
. function to allocate a block of global memory and then fills the memory 
with the packed DIB. A packed DIB consists of a BITMAPINFO data 
structure immediately followed by the array of bytes which define the pix- 
els of the bitmap. 


_ If IbStyle is BS_HATCHED, the IbHatch field specifies the orientation of 
the lines used to create the hatch. It can be any one of the following 


values: 

Value Meaning 

HS_BDIAGONAL 45-degree upward hatch (left to right) 
HS_CROSS Horizontal and vertical crosshatch 
HS_DIAGCROSS 45-degree crosshatch 

HS_FDIAGONAL 45-degree downward hatch (left to right) 
HS_HORIZONTAL Horizontal hatch | 

HS_VERTICAL Vertical hatch 


If IbStyle is BS_PATTERN, IbHatch must be a handle to the bitmap that 
defines the pattern. 


If IbStyle is BS_SOLID or BS_HOLLOW, IbHatch is ignored. 


See Also The CreateBrushIndirect function in Chapter 4, “Functions Directory,” in Reference, 
Volume 1. 


LOGFONT = 
Logical-Font Descriptor 


The LOGFONT structure defines the attributes of a font, a crawang object used to write 
text on a display surface. 
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LOGFONT 


typedef struct tagLOGFONT { 


short int 
short int 
short int 
short int 
short int 
BYTE 
BYTE 
BYTE 
BYTE 
BYTE 
BYTE 
BYTE 
BYTE 
BYTE 
} LOGFONT; 


lfHeight; 
1fWidth; 
1fEscapement; 
1fOrientation; 
1fWeight; 
lfItalic; 
1fUnderline; 
1fStrikeOut; 
1fCharSet; 
1fOutPrecision; 
1fClipPrecision; 
1fQuality; 
1fPitchAndFamily; 
1fFaceName[LF_FACESIZE]; 


The LOGFONT structure has the following fields: 


Field 
IfHeight 


IfWidth 


IfEscapement 


IfOrientation 


Description 


Specifies the average height of the font (in user units). The 
height of a font can be specified in the following three ways. If 
the IfHeight field is greater than zero, it is transformed into 
device units and matched against the cell height of the availa- 
ble fonts. If IfHeight is zero, a reasonable default size is used. 
If IfHeight is less than zero, it is transformed into device units 
and the absolute value is matched against the character height 
of the available fonts. 


Specifies the average width of characters in the font (in device 
units). If the IfWidth field is zero, the aspect ratio of the 
device is matched against the digitization aspect ratio of the 
available fonts for the closest match by absolute value of the 
difference. 


Specifies the angle (in tenths of degrees) between the escape- 
ment vector and the x-axis of the display surface. The 
escapement vector is the line through the origins of the first 
and last characters on a line. The angle is measured counter- 
clockwise from the x-axis. 


Specifies the angle (in tenths of degrees) between the baseline 
of a character and the x-axis. The angle is measured counter- 
clockwise from the x-axis. 
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Field 
IfWeight 


IfItalic 
IfUnderline 
IfStrikeOut 
IfCharSet 


1fOutPrecision 


IfClipPrecision 


IfQuality 


Description 


Specifies the font weight (in inked pixels per 1000). Although 
the IfWeight field can be any integer value from 0 to 1000, the 
common values are as follows: 


400 Normal 
700 Bold 


These values are approximate; the actual appearance depends 
on the font face. If IfWeight is zero, a default weight is used. 


Specifies an italic font if set to nonzero. 
Specifies an underlined font if set to nonzero. 
Specifies a strikeout font if set to nonzero. 


Specifies the font’s character set. The three values are 
predefined: 


ANSI_CHARSET 
OEM_CHARSET 
SYMBOL_CHARSET 


The OEM character set is system-dependent. 


Fonts with other character sets may exist in the system. If an 
application uses a font with an unknown character set, it 
should not attempt to translate or interpret strings that are to be 
rendered with that font. Instead, the strings should be passed 
directly to the output device driver. 


Specifies the font’s output precision, which defines how 
closely the output must match the requested font’s height, 
width, character orientation, escapement, and pitch. The de- 
fault setting is OUT_.DEFAULT_PRECIS. 


Specifies the font’s clipping precision, which defines how to 
clip characters that are partially outside the clipping region. 
The default setting is CLIP_DEFAULT_PRECIS. 


Specifies the font’s output quality, which defines how carefully 
GDI must attempt to match the logical-font attributes to those 
of an actual physical font. It can be any one of the following 
values: 
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Field 


IfPitchAndFamily 


Description 


Value 


DEFAULT_QUALITY 


DRAFT_QUALITY 


PROOF_QUALITY 


Meaning 


Appearance of the font does not 
matter. 


Appearance of the font is less 
important than when 
PROOF_QUALITY is used. 
For GDI fonts, scaling is 
enabled, which means that 


_ more font sizes are available, 


but the quality may be lower. 
Bold, italic, underline, and 
strikeout fonts are synthesized 
if necessary. 


Character quality of the font is 
more important than exact 
matching of the logical-font at- 
tributes. For GDI fonts, scaling 
is disabled and the font closest 
in size is chosen. Although the 
chosen font size may not be 
mapped exactly when 
PROOF_QUALITY is used, the 
quality of the font is high and 
there is no distortion of appear- 
ance. Bold, italic, underline, 
and strikeout fonts are synthe- 
sized if necessary. 


Specifies the font pitch and family. The two low-order bits 
specify the pitch of the font and can be any one of the follow- 


ing values: 


DEFAULT_PITCH 
FIXED_PITCH 
VARIABLE_PITCH 


The four high-order bits of the field specify the font family and 
can be any one of the following values: 
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Field 


IffaceName 


Description 


FF_DECORATIVE 
FF_DONTCARE 
FF_MODERN 
FF_ROMAN 
FF_SCRIPT 
FF_SWISS 


The proper value can be obtained by using the Boolean OR 
operator to join one pitch constant with one family constant. 


Font families describe the look of a font in a general way. They 
are intended for specifying fonts when the exact typeface 
desired is not available. The values for font families are as fol- 
lows: 


Value Meaning 
FF_DECORATIVE Novelty fonts. 
FF_DONTCARE Don’t care or don’t know. 
FF_MODERN Fonts with constant stroke 


width (fixed-pitch), with or 
without serifs. Fixed-pitch fonts 
are usually modern. 


FF_ROMAN Fonts with variable stroke 
width (proportionally spaced) 
and with serifs. 


FF_SCRIPT Fonts designed to look like 
handwriting. 
FF_SWISS Fonts with variable stroke 


width (proportionally spaced) 
and without serifs. 


Specifies the font’s typeface. It must be a null-terminated 
character string. If IfFaceName is NULL, GDI uses a default 
typeface. 
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See Also The CreateFontIndirect function in Chapter 4, “Functions Directory,” in Reference, 
Volume 1. 


LOGPALETTE 
Logical Color Palette Information 
The LOGPALETTE data structure defines a logical color palette. 


typedef struct 
{ 


WORD palVersion; 
WORD palNumEntries; 
PALETTEENTRY palPalEntry(]; 
} LOGPALETTE; 


The LOGPALETTE structure has the following fields: 


Field Description 

pal Version Specifies the Windows version number for the structure (cur- 
rently 0x300). 

palNumEntries Specifies the number of palette color entries. 

palPalEntry [ ] Specifies an array of PALETTEENTRY data structures that 


define the color and usage of each entry in the logical palette. 


Comments The colors in the palette entry table should appear in order of importance. This is because 
entries earlier in the logical palette are most likely to be placed in the system palette. 


This data structure is passed as a parameter to the CreatePalette function. 


LOGPEN 


Logical-Pen Attribute Information 


The LOGPEN structure defines the style, width, and color of a pen, a drawing object used 
to draw lines and borders. The CreatePenIndirect function uses the LOGPEN structure. 


typedef struct tagLOGPEN {. 
WORD lopnStyle; 
POINT lopnWidth; 
COLORREF JlopnColor; 

} LOGPEN; 


LOGPEN 7-46 

The LOGPEN structure has the following fields: 

Field Description 

lopnStyle Specifies the pen type, which can be any one of 
the following values: . 
Constant Name Value Result 
PS_SOLID 0 — 
PS_DASH \ —-- 
PS_DOT 2 
PS_DASHDOT 3 —.- 
PS_DASHDOTDOT ; 4 Sh ae 
PS_NULL 5 
PS_INSIDEFRAME 6 


Comments 


See Also 


If the width of the pen is greater than 1 and the pen style is 
PS_INSIDEFRAME, the line is drawn inside the frame of all 
primitives except polygons and polylines; the pen is drawn 
with a logical (dithered) color if the pen color does not match 
an available RGB value. The PS_INSIDEFRAME style is 
identical to PS_SOLID if the pen width is less than or equal 
to 1. 


lopnWidth Specifies the pen width (in logical units). If the 
lopnWidth field is zero, the pen is one pixel 
wide on raster devices. 


lopnColor Specifies the pen color. 


The y value in the POINT structure for lopn Width is not used. 


The CreatePenIndirect function in Chapter 4, “Functions Directory,” in Reference, 
Volume 1. : 
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MDICREATESTRUCT 
MDI Child Window Creation Structure 


The MDICREATESTRUCT data structure contains information about the class, title, 
owner, location, and size of a multiple document interface (MDI) child window. 


typedef struct tagMDICREATESTRUCT 
{ 
LPSTR szClass; 
LPSTR szTitle; 
HANDLE hQwner; 


int x3 

int y3 

int CX; 

int cy; 

LONG style; 

LONG lParam; 
} MDICREATESTRUCT; 


The MDICREATESTRUCT structure contains the following fields: 


Field Description 

szClass Contains a long pointer to the application-defined class of the 
MDI child window. 

szTitle Contains a long pointer to the window title of the MDI child 
window. 

hOwner Is the instance handle of the application creating the MDI child 
window. 

x Specifies the initial position of the left side of the MDI child 


window. If set to CW_USEDEFAULT, the MDI child window 
is assigned a default horizontal position. 


y Specifies the initial position of the top edge of the MDI child 
window. If set to CW_USEDEFAULT, the MDI child window 
is assigned a default vertical position. 


cx Specifies the initial width of the MDI child window. If set to 
CW_USEDEFAULT, the MDI child window is assigned a 
default width. 

cy Specifies the initial height of the MDI child window. If set to 


CW_USEDEFAULT, the MDI child window is assigned a 
default height. 
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Field Description 


style Specifies additional styles for the MDI child window. The style 
field may be set to one or more of the following values: 


Value Meaning 


WS_MINIMIZE The MDI child window is created in a 
minimized state. 


WS_MAXIMIZE The MDI child window is created in a 
maximized state. 


WS_HSCROLL The MDI child window is created with a 


horizontal scroll bar. 
WS_VSCROLL The MDI child window is created with a 
vertical scroll bar. 
]Param ~ Ts an application-defined 32-bit value. 
Comments When the MDI child window is created, Windows sends the WM_CREATE message to 


the window. The /Param parameter of the WM_CREATE message contains a pointer to a 

CREATESTRUCT data structure. The IpCreateParams field of the CREATESTRUCT 
structure contains a pointer to the MDICREATESTRUCT data structure passed with the 

WM_MDICREATE message that created the MDI child window. 


MEASUREITEMSTRUCT 


Owner-Draw Contro! Dimensions 


The MEASUREITEMSTRUCT data structure informs Windows of the dimensions of an 
owner-draw control. This allows Windows to process user interaction with the control cor- 
rectly. The owner of an owner-draw control receives a pointer to this structure as the 
[Param parameter of an WM_MEASUREITEM message. The owner-draw control sends 
this message to its owner window when the control is created; the owner then fills in the 
appropriate fields in the structure for the control and returns. This structure is common to 
all owner-draw controls. 


The MEASUREITEMSTRUCT structure has the following format: 
typedef struct tagMEASUREITEMSTRUCT 


WORD CtlType; 
WORD CtlID; 
WORD  itemID; 
WORD  itemWidth; 
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WORD ijtemHeight; 
DWORD 
} MEASUREITEMSTRUCT; 


The MEASUREITEMSTRUCT structure contains the following fields: 


Field 
CtlType 


CtlID 


itemID 


item Width 


itemHeight 


itemData 


Description 


Is the control type. The values for control types are as follows: 


Value Meaning 
ODT_BUTTON Owner-draw button. 
ODT_COMBOBOX Owner-draw combo box. 
ODT_LISTBOX Owner-draw list box. 
ODT_MENU Owner-draw menu. 


Is the control ID for a combo box, list box, or button. This field 
is not used for a menu. 


Is the menu-item ID for a menu or the list-box item ID for a vari- 
able-height combo box or list box. This field is not used for a 
fixed-height combo box or list box, or for a button. 


Specifies the width of a menu item. The owner of the owner- 
draw menu item must fill this field before returning from the 
message. 


Specifies the height of an individual item in a list box or a menu. 
Before returning from the message, the owner of the owner- 
draw combo box, list box, or menu item must fill out this field. 


Contains the value that was passed to the combo box or list box 
in the /Param parameter of one of the following messages: . 


u CB_ADDSTRING 
= CB_INSERTSTRING 
= LB_ADDSTRING 
= LB_INSERTSTRING 


Contains the DWORD value passed as the /pNewltem parameter 
of the AppendMenu, InsertMenu, or ModifyMenu function 
that added or modified the menu item. Its contents are undefined 
for buttons. 
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Comments Failure to fill out the proper fields in the MEASUREITEM structure will cause improper 
operation of the control. 


MENUITEMTEMPLATE 


Menu-ItemTemplate 


A complete menu template consists of a header and one or more menu-item lists. The fol- 
lowing shows the structure of the menu-template header: 


typedef struct { 
WORD versionNumber; 
WORD offset; 

} MENUITEMTEMPLATEHEADER; 


The menu-template header contains the following fields: 


Field Description 
versionNumber Specifies the version number. Should be zero. 
offset Specifies the offset from the header in bytes where the 


menu-item list begins. 


One or more MENUITEMTEMPLATE structures are combined to form the menu-item 
list. 


typedef struct { 
WORD mtOption; 
WORD mtID; 
LPSTR mtString; 
} MENUITEMTEMPLATE; 


The MENUITEMTEMPLATE structure has the following fields: 


Field Description 


mtOption Specifies a mask of one or more predefined menu options that 
specify the appearance of the menu item. The menu options are as 
follows: 
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Field Description 

Value Meaning 

MF_CHECKED Item has a checkmark next to it. 

MF_END Item must be specified for the last 
item in a pop-up menu or a Static 
menu. 

MF_GRAYED Item is initially inactive and drawn 
with a gray effect. 

MF_HELP Item has a vertical separator to its 
left. 


MF_MENUBARBREAK Item is placed in a new column. The 
old and new columns are separated 


by a bar. 
MF_MENUBREAK Item is placed in a new column. 
MF_OWNERDRAW The owner of the menu is re- 


sponsible for drawing all visual 
aspects of the menu item, including 
highlighted, checked and inactive 
states. This option is not valid for a 
top-level menu item. 


MF_POPUP Item displays a sublist of menu 
items when selected. 


mtID Specifies an identification code for a nonpop-up menu item. The 
MENUITEMTEMPLATE data structure for a pop-up menu item 
does not contain the mtID field. 


mtString Points to a null-terminated character string that specifies the name 
of the menu item. 


See also The LoadMenulIndirect function in Chapter 4, “Functions Directory,” in Reference, 
Volume 1. 
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METAFILEPICT 


Metafile Picture Structure 


The METAFILEPICT structure defines the metafile picture format used for exchanging 
metafile data through the clipboard. 


typedef struct tagMETAFILEPICT { 


int mm ; 
int XExt, yExt; 
HANDLE hMF; 

} METAFILEPICT; 


The METAFILEPICT structure has the following fields: 


Field Description 
mm Specifies the mapping mode in which the picture is drawn. 
xExt Specifies the size of the metafile picture for all modes except the 


MM_ISOTROPIC and MM_ANISOTROPIC modes. The x-extent speci- 
fies the width of the rectangle within which the picture is drawn. The 
coordinates are in units that correspond to the mapping mode. 


yExt Specifies the size of the metafile picture for all modes except the 
MM_ISOTROPIC and MM_ANISOTROPIC modes. The y-extent speci- 
fies the height of the rectangle within which the picture is drawn. The 
coordinates are in units that correspond to the mapping mode. 


For MM_ISOTROPIC and MM_ANISOTROPIC modes, which can be 
scaled, the xExt and yExt fields contain an optional suggested size in 
MM_HIMETRIC units. For MM_ANISOTROPIC pictures, xExt and 
yExt can be zero when no suggested size is supplied. For 
MM_ISOTROPIC pictures, an aspect ratio must be supplied even when 
no suggested size is given. (If a suggested size is given, the aspect ratio 
is implied by the size.) To give an aspect ratio without implying a sug- 
gested size, set xExt and yExt to negative values whose ratio is the 
appropriate aspect ratio. The magnitude of the negative xExt and yExt 
values will be ignored; only the ratio will be used. 


hMF Identifies a memory metafile. 
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MSG 
Message Data Structure 
The MSG structure contains information from the Windows application queue. 


typedef struct tagMSG { 
HWND hwnd; 


DWORD time; 
POINT pi; 
) MSG; 


The MSG structure has the following fields: 


Field Description 

hwnd Identifies the window that receives the message. 

message Specifies the message number. 

wParam Specifies additional information about the message. The exact meaning 
depends on the message value. 

]Param Specifies additional information about the message. The exact meaning 
depends on the message value. 

time Specifies the time at which the message was posted. 

pt Specifies the position of the cursor (in screen coordinates) when the 


message was posted. 


MULTIKEYHELP 
Windows Help Key Word Table Structure 


The MULTIKEYHELP structure specifies a key-word table and an associated key word 
to be used by the Windows Help application. 


typedef struct tagMULTIKEYHELP { 
WORD mkSize; 
BYTE mkKeylist; 
BYTE szKeyphraseL]; 

} MULTIKEYHELP; 


‘The MULTIKEYHELP data structure contains the following fields: 
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Field Description 
mkSize Specifies the length of the MULTIKEYHELP structure (in 
bytes). 
mkKeylist Contains a single character that identifies the key-word table to 
be searched. 
szKeyphrase[ ] Contains a null-terminated text string that specifies the key word 


OFSTRUCT 


Open-File Structure 


to be located in the key-word table. 


The OFSTRUCT structure contains file information which results from opening that file. 


typedef struct tagOFSTRUCT { 
BYTE cBytes; 
BYTE fFixedDisk; 
WORD nErrCode; 
BYTE reserved[4]; 
BYTE szPathNameLl12@]; 
} OFSTRUCT; 


The OFSTRUCT structure has the following fields: 


Field Description 
cBytes Specifies the length of the OFSTRUCT structure (in bytes). 
fFixedDisk Specifies whether the file is on a fixed disk. The fFixedDisk 


field is nonzero if the file is on a fixed disk. 


nErrCode Specifies the DOS error code if the OpenFile function returns 
—1 (that is, OpenFile failed). 


reserved[4] Reserved field. Four bytes reserved for future use. 


szPathName[120] Specifies 120 bytes that contain the pathname of the file. This 
string consists of characters from the OEM character set. 
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PAINTSTRUCT 


Windows Paint Information 


The PAINTSTRUCT structure contains information for an application. This information 
can be used to paint the client area of a window owned by that application. 


typedef struct tagPAINTSTRUCT { 
HDC hdc; 
BOOL fErase; 
RECT rcPaint; 
BOOL fRestore; 
BOOL fIncUpdate; 
BYTE rgbReserved[16]; 
} PAINTSTRUCT; 


The PAINTSTRUCT structure has the following fields: 


Field Description 

hde Identifies the display context to be used for painting. 

fErase Specifies whether the background has been redrawn. It has been 
redrawn if nonzero. 

rcPaint Specifies the upper-left and lower-right comers of the rectangle 
in which the painting is requested. 

fRestore Reserved field. It is used internally by Windows. 

fIncUpdate Reserved field. It is used internally by Windows. 


rgbReserved[16] Reserved field. A reserved block of memory used internally by 
Windows. 


PALETTEENTRY 


Logical Palette Color Entry 


The PALETTEENTRY data structure specifies the color and usage of an entry in a logi- 
cal color palette. A logical palette is defined by a LOGPALETTE data structure. 


typedef struct 
{ 
BYTE peRed; 
BYTE peGreen; 
BYTE peBlue; 
BYTE peFlags; 
} PALETTEENTRY,; 


POINT 7-56 


The PALETTEENTRY structure contains the following fields: 


Field — Description 

peRed Specifies the intensity of red for the palette entry color. 

peGreen Specifies the intensity of green for the palette entry color. 

peBlue Specifies the intensity of blue for the palette entry color. 

peFlags Specifies how the palette entry is to be used. The peFlags field may be 
set to NULL or one of these values: 
Flag Meaning 
PC_EXPLICIT Specifies that the low-order word of the 


logical palette entry designates a hard- 

ware palette index. This flag allows the 
application to show the contents of the 

display-device palette. 


PC_NOCOLLAPSE Specifies that the color will be placed in 
an unused entry in the system palette in- 
stead of being matched to an existing 
color in the system palette. If there are no 
unused entries in the system palette, the 
color is matched normally. Once this 
color is in the system palette, colors in 
other logical palettes can be matched to 
this color. 


PC_RESERVED Specifies that the logical palette entry 
will be used for palette animation; this 
prevents other windows from matching 
colors to this palette entry since the color 
will frequently change. If an unused sys- 
tem-palette entry is available, this color 
is placed in that entry. Otherwise, the 
color will not be available for animation. 


POINT 


Point Data Structure 


_ The POINT structure defines the x- and y-coordinates of a point. 
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RECT 


See Also 


RECT 


typedef struct tagPOINT { 
int x; 
int y; 

} POINT; 


The POINT structure has the following fields: 


Field Description 
Xx Specifies the x-coordinate of a point. 


y Specifies the y-coordinate of a point. 


The ChildWindowFromPoint, PtInRect, and WindowFromPoint functions in Chapter 
4, “Functions Directory,” in Reference, Volume 1, 


Rectangle Data Structure 


Comments 


The RECT structure defines the coordinates of the upper-left and lower-right corners of a 
rectangle. 


typedef struct tagRECT { 
int left; 
int top; 
int right; 
int bottom; 
} RECT; 


The RECT structure has the following fields: 


Field Description 

left Specifies the x-coordinate of the upper-left corner of a rectangle. 
top Specifies the y-coordinate of the upper-left corner of a rectangle. 
right Specifies the x-coordinate of the lower-right corner of a rectangle. 
bottom Specifies the y-coordinate of the lower-right corner of a rectangle. 


The width of the rectangle defined by the RECT structure must not exceed 32,768 units. 
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RGBQUAD 
RGB Color Structure 


The RGBQUAD data structure describes a color consisting of relative intensities of red, 
green, and blue. The bmiColors field of the BITMAPINFO data structure consists of an 
array of RGBQUAD data structures. 


typedef struct tagRGBQUAD { 
BYTE rgbBlue; 
BYTE rgbGreen; 
BYTE rgbRed; 
BYTE rgbReserved; 
} RGBQUAD; 


The RGBQUAD structure contains the following fields: 


Field Description 

rgbBlue Specifies the intensity of blue in the color. 
rgbGreen Specifies the intensity of green in the color. 
rgbRed Specifies the intensity of red in the color. 
rgbReserved Is not used and must be set to zero. 


RGBTRIPLE 
RGB Color Structure 


The RGBTRIPLE data structure describes a color consisting of relative intensities of red, 
green, and blue. The bmciColors field of the BITMAPCOREINFO data structure con- 
sists of an array of RGBTRIPLE data structures. 


typedef struct tagRGBTRIPLE { 
BYTE rgbtBlue; 
BYTE rgbtGreen; 
BYTE rgbtRed; 

} RGBTRIPLE; 


The RGBTRIPLE structure contains the following fields: 
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Field Description 
rgbtBlue Specifies the intensity of blue in the color. 
rgbtGreen Specifies the intensity of green in the color. 
rgbtRed Specifies the intensity Of red in the color. 
TEXTMETRIC 


Basic Font Metrics 


The TEXTMETRIC structure contains basic information about a physical font. All sizes 
are given in logical units; that is, they depend on the current mapping mode of the display 


context. 


typedef struct tagTEXTMETRIC { 


short int 

short int 

short int 

short int 

short int 

short int 

short int 

short int 

BYTE 

BYTE 

BYTE 

BYTE 

BYTE 

BYTE 

BYTE 

BYTE 

BYTE 

Short int 

short int 

short int 
} TEXTMETRIC; 


tmHeight; 

tmAscent; 
tmDescent; 
tmInternal Leading; 
tmExternalLeading; 
tmAveCharWidth; 
tmMaxCharWidth; 
tmWeight; 

tmitalic; 
tmUnderlined; 
tmStruckOut; 
tmFirstChar; 
tmLastChar; 
tmDefaultChar; 
tmBreakChar; 
tmPitchAndFamily; 
tmCharSet; 
tmOverhang; 
tmDigitizedAspectx; 
tmDigitizedAspectyY; 


The TEXTMETRIC structure has the following fields: 


Field 


tmHeight 


tmAscent 


Description 
Specifies the height (ascent + descent) of characters. 


Specifies the ascent (units above the baseline) of 
characters. 


TEXTMETRIC 


Field 


tmDescent 


tmInternalLeading 


tmExternalLeading 


tmAveCharWidth 


tmMaxChar Width 
tm Weight 

tmlItalic 
tmUnderlined 
tmStruckOut 
tmFirstChar 


tmLastChar 


tmDefaultChar 


tmBreakChar 


tmPitchAndFamily 
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Description 


Specifies the descent (units below the baseline) of 
characters. 


Specifies the amount of leading (space) inside the 
bounds set by the tmHeight field. Accent marks and 
other foreign characters may occur in this area. The de- 
signer may set this field to zero. 


Specifies the amount of extra leading (space) that the 
application adds between rows. Since this area is outside 
the font, it contains no marks and will not be altered by 
text output calls in either OPAQUE or TRANSPARENT 
mode. The designer may set this field to zero. 


Specifies the average width of characters in the font 
(loosely defined as the width of the letter x). This value 
does not include overhang required for bold or italic 
characters. 


Specifies the width of the widest character in the font. 
Specifies the weight of the font. 

Specifies an italic font if it is nonzero. 
Specifies an underlined font if it is nonzero. 
Specifies a struckout font if it is nonzero. 


Specifies the value of the first character defined in the 
font. 


Specifies the value of the last character defined in the 
font. 


Specifies the value of the character that will be substi- 
tuted for characters that are not in the font. 


Specifies the value of the character that will be used to 
define word breaks for text justification. 


Specifies the pitch and family of the selected font. The 
low-order bit specifies the pitch of the font. If it is 1, the 
font is variable pitch. If it is 0, the font is fixed pitch. 
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Field Description 


The four high-order bits designate the font family. The 
tmPitchAndFamily field can be combined with the hex- 
adecimal value OxFO by using the bitwise AND operator, 
and then be compared with the font family names for an 
identical match. For a description of the font families, 
see the LOGFONT structure, earlier in this chapter. 


tmCharSet Specifies the character set of the font. 


tmOverhang Specifies the per-string extra width that may be added to 
some synthesized fonts. When synthesizing some at- 
tributes, such as bold or italic, GDI or a device may have 
to add width to a string on both a per-character and per- 
string basis. For example, GDI makes a string bold by 
expanding the intracharacter spacing and overstriking by 
an offset value; it italicizes a font by skewing the string. 
In either case, there is an overhang past the basic string. 
For bold strings, the overhang is the distance by which 
the overstrike is offset. For italic strings, the overhang is 
the amount the top of the font is skewed past the bottom 
of the font. 


The tmOverhang field allows the application to deter-. 
mine how much of the character width returned by a 
GetTextExtent function call on a single character is the 
actual character width and how much is the per-string 
extra width. The actual width is the extent minus the 
overhang. 


tmDigitizedAspectX Specifies the horizontal aspect of the device for which 
the font was designed. 


tmDigitizedAspectY Specifies the vertical aspect of the device for which the 
font was designed. The ratio of the tmDigitizedAspectX 
and tmDigitizedAspectY fields is the aspect ratio of the 
device for which the font was designed. 


9 


See Also The GetDeviceCaps and GetTextMetrics functions in Chapter 4, “Functions Directory,’ 
in Reference, Volume 1. 
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WNDCLASS 


Window-Class Data Structure 


The WNDCLASS structure contains the class attributes that are registered by the 
RegisterClass function. 


typedef struct tagWNDCLASS { 
WORD style; 
long (FAR PASCAL *lpfnWndProc)(); 
int cbClsExtra; 
int cbWndExtra; 
HANDLE hInstance; 
HICON hIcon; 
HCURSOR hCursor; 
HBRUSH hbrBackground; 
LPSTR lpszMenuName; 
LPSTR lpszClassName; 

} WNDCLASS; 


The WNDCLASS structure has the following fields: 


Field Description 


style Specifies the class style. These styles can be combined by using 
the bitwise OR operator. The style field can be any combination 
of the following values: 


Value | Meaning 


CS_BYTEALIGNCLIENT Aligns a window’s client area 
on the byte boundary (in the 
x direction). 


CS_BYTEALIGNWINDOW Aligns a window on the byte 
boundary (in the x direction). 


CS_CLASSDC Gives the window class its 
own display context (shared 
by instances). 


CS_DBLCLKS Sends double-click messages 
to a window. 
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WNDCLASS 


Field Description 


Value 


CS_GLOBALCLASS 


CS_HREDRAW 
CS_NOCLOSE 


CS_OWNDC 


CS_PARENTDC 


Meaning 


Specifies that the window 
class is an application global 
class. An application global 
class is created by an applica- 
tion or library and is 
available to all applications. 
The class is destroyed when 
the application or library that 
created the class terminates; 
it is essential, therefore, that 
all windows created with the 
application global class be 
closed before this occurs. 


Redraws the entire window if 
the horizontal size changes. 


Inhibits the close option on 
the System menu. 


Gives each window instance 
its own display context. Note 
that although the 
CS_OWNDC style is con- 
venient, it must be used with 
discretion because each dis- 
play context occupies 
approximately 800 bytes of 
memory. 


Gives the parent window’s 
display context to the 
window class. 


WNDCLASS 


Field 


IpfnWndProc 
cbClsExtra 


cbWndExtra 


hInstance 


Description 


Value 


CS_SAVEBITS 


CS_VREDRAW 


Points to the window function. 
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Meaning 


Saves the portion of the 
screen image that is obscured 
by a window; Windows uses 
the saved bitmap to re-create 
a screen image when the 
window is removed. 
Windows displays the bitmap 
at its original location and 
does not send WM_PAINT 
messages to windows which 
had been obscured by the 
window if the memory used 
by the bitmap has not been 
discarded and if other screen 
actions have not invalidated 
the stored image. An applica- 
tion should set this bit only 
for small windows that are 
displayed briefly and then re- 
moved before much other 
screen activity takes place. 
Setting this bit for a window 
increases the amount of time 
required to display the 
window due to the time re- 
quired to allocate memory to 
store the bitmap. 


Redraws the entire window if 
the vertical size changes. 


Specifies the number of bytes to allocate following the window- 


class structure. 


Specifies the number of bytes to allocate following the window 
instance. If an application is using the WNDCLASS structure to 
register a dialog box created with the CLASS directive in the 
-RC script file, it must set this field to DLGWINDOWEXTRA. 


Identifies the class module. The hInstance field must be an in- 
stance handle and must not be NULL. 
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Field Description 


hIcon Identifies the class icon. The hIcon field must be a handle to an 
icon resource. If hIcon is NULL, the application must draw an 
icon whenever the user minimizes the application’s window. 


hCursor Identifies the class cursor. The hCursor field must be a handle 
to a cursor resource. If hCursor is NULL, the application must 
explicitly set the cursor shape whenever the mouse moves into 
the application’s window. 


hbrBackground Identifies the class background brush. The hbrBackground 
field can be either a handle to the physical brush that is to be 
used for painting the background, or it can be a color value. If a 
color value is given, it must be one of the standard system colors 
listed below, and the value 1 must be added to the chosen color 
(for example, COLOR_.BACKGROUND + | specifies the sys- 
tem background color). If a color value is given, it must be 
converted to one of the following HBRUSH types: 


COLOR_ACTIVEBORDER 
COLOR_ACTIVECAPTION 
COLOR_APPWORKSPACE 
COLOR_BACKGROUND 
COLOR_BTNFACE 
COLOR_BTNSHADOW 
COLOR_BTNTEXT 
COLOR_CAPTIONTEXT 
COLOR_GRAYTEXT 
COLOR_HIGHLIGHT 
COLOR_HIGHLIGHTTEXT 
COLOR_INACTIVEBORDER 
COLOR_INACTIVECAPTION 
COLOR_MENU 
COLOR_MENUTEXT 
COLOR_SCROLLBAR 
COLOR_WINDOW 
COLOR_WINDOWFRAME 
COLOR_WINDOWTEXT 


When hbrBackground is NULL, the application must paint its 
own background whenever it is requested to paint in its client 
area. The application can determine when the background needs 
painting by processing the WM_ERASEBKGND message or by 
testing the fErase field of the PAINTSTRUCT structure filled 
by the BeginPaint function. 


WNDCLASS 


Field 


IpszMenuName 


IpszClassName 
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Description 


Points to a null-terminated character string that specifies the 
resource name of the class menu (as the name appears in the 
resource file). If an integer is used to identify the menu, the 
MAKEINTRESOURCE macro can be used. If the 
IpszMenuName field is NULL, windows belonging to this class 
have no default menu. 


Points to a null-terminated character string that specifies the 
name of the window class. 


Chapter || Resource Script Statements 
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This chapter describes the statements that define resources that the Microsoft 
Windows Resource Compiler (RC) adds to an application’s executable file. See 
Tools for information on running the Resource Compiler. 


This chapter describes resource script statements in the following categories: 


= Single-line statements 

= User-defined resources 

= RCDATA statement 

m= STRINGTABLE statement 

= ACCELERATORS statement 
m Menu statements 

= Dialog statements 


= Directives 


8.1 Single-Line Statements 


The single-line statements define resources that are contained in a single file, 
such as cursors, icons, and fonts. The statements associate the filename of the 
resource with an identifying name or number. The resource is added to the exe- 
cutable file when the application is created, and can be extracted during execu- 
tion by referring to the name or number. 


The following is the general form for all single-line statements: 


namelD resource-type {lload-option]| [[mem-option] filename 


The namelD field specifies either a unique name or an integer value identifying 
the resource. For a font resource, nameID must be a number; it cannot be a name. 


The resource-type field specifies one of the following key words, which identify 
the type of resource to be loaded: 
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Key word Resource Type 

CURSOR Specifies a bitmap that defines the shape of the 
cursor on the display screen. 

ICON Specifies a bitmap that defines the shape of the icon 
to be used for a given application. 

BITMAP Specifies a custom bitmap that an application is 

going to use in its screen display or as an item ina 

menu. 

FONT Specifies a file that contains a font. 


The optional /oad-option field takes a key word that specifies when the resource 
is to be loaded. The key word must be one of the following: 


Option Description 

PRELOAD Resource is loaded immediately. 

LOADONCALL Resource is loaded when called. This is the default 
option. 


NOTE \conand cursor resources can contain more than one image. If the resource is 
marked as PRELOAD, Windows loads all images in the resource when the application ex- 
ecutes. 


The optional mem-option field takes the following key word or key words, which 
specify whether the resource is fixed or moveable and whether it is discardable: 


Option Description 

FIXED Resource remains at a fixed memory location. 

MOVEABLE Resource can be moved if necessary in order to 
compact memory. 

DISCARDABLE Resource can be discarded if no longer needed. 


The default is MOVEABLE and DISCARDABLE for cursor, icon, and font 
resources. The default for bitmap resources is MOVEABLE. 


The filename field is an ASCII string that specifies the DOS filename of the file 
that contains the resource. A full pathname must be given if the file is not in the 
current working directory. 
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The following example demonstrates the correct usage for a single-line statement: 


cursor CURSOR point.cur 
cursor CURSOR DISCARDABLE point.cur 
10 CURSOR custom.cur 


desk ICON desk.ico 
desk ICON DISCARDABLE desk.ico 
11 ICON custom.ico 


disk BITMAP disk. bmp 
disk BITMAP DISCARDABLE disk.bmp 
12 BITMAP custom. bmp 


5 FONT CMROMAN. FNT 


8.2 User-Defined Resources 


An application can also define its own resource. The resource can be any data 
that the application intends to use. A user-defined resource statement has the fol- 
lowing form: 


namelD typelD [load-option] [[mem-option] {[filename] | 
[BEGIN 

raw-data 

END]} 


The namelD field specifies either a unique name or an integer value that identi- 
fies the resource. 


The typelD field specifies either a unique name or an integer value that identifies 
the resource type. If a number is given, it must be greater than 255. The numbers 
1 through 255 are reserved for existing and future predefined resource types. 


The optional load-option field takes a key word that specifies when the resource 
is to be loaded. The key word must be one of the following: - 


Option Description 

PRELOAD Resource is loaded immediately. 

LOADONCALL Resource is loaded when called. This is the default 
option. 


The optional mem-option field takes the following key word or key words, which 
specify whether the resource is fixed or moveable and whether it is discardable: 
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Option Description 

FIXED Resource remains at a fixed memory location. 

MOVEABLE Resource can be moved if necessary in order to com- 
pact memory. This is the default option. 

DISCARDABLE Resource can be discarded if it is no longer needed. 


The optional filename field is an ASCII string that specifies the DOS filename of 
the file that contains the resource. A full pathname must be given if the file is not 
in the current working directory. Do not use the filename field if you supply raw 
data between the optional BEGIN and END statements. 


The raw-data field specifies one or more integers and strings. Integers can be in 
decimal, octal, or hexadecimal format. Do not use raw-data field and the BEGIN" 
and END statements if you specify a filename. 


The following example demonstrates the correct usage for user-defined state- 
ments: 


array MYRES data.res 


14 3908 custom.res 
18 MYRES2 
BEGIN 


"Here is a data string\@", /* A string. Note: explicitly 
null-terminated */ 


1024, /* int */ 
Ox@29a, /* hex int * / 
00733, /* octal int */ 
"\O7" /* octal byte */ 

END 

8.3 RCDATA Statement 

Syntax 

nameID RCDATA [load-option]] [mem-option] 

BEGIN 

raw-data 

END 


The RCDATA statement defines a raw data resource for an application. Raw 
data resources permit the inclusion of binary data directly in the executable file. 


The namelD field specifies either a unique name or an integer value that identi- 
fies the resource. 


The optional /oad-option field takes a key word that specifies when the resource 
is to be loaded. It must be one of the following: 
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Option Description 

PRELOAD Resource is loaded immediately. 

LOADONCALL ~ Resource is loaded when called. This is the default 
option. 


The optional mem-option field takes the following key word or key words, which 
specify whether the resource is fixed or moveable and whether it is discardable: 


Option Description 

FIXED Resource remains at a fixed memory location. 

MOVEABLE Resource can be moved if necessary in order to 
compact memory. 

DISCARDABLE Resource can be discarded if no longer needed. 


The default is MOVEABLE and DISCARDABLE. 


The raw-data field specifies one or more integers and strings. Integers can be in 
decimal, octal, or hexadecimal format. 


The following example demonstrates the correct usage for the RCDATA 
statement: 


resname RCDATA 
BEGIN 
"Here is a data string\®", /* A string. Note: explicitly 
null-terminated */ 


1024, /* int */ 
Qx929a, /* hex int | 
80733, /* octal int */ 
"\Q7" /* octal byte */ 

END 

8.4 STRINGTABLE Statement 

Syntax 

STRINGTABLE [lJoad-option] [[mem-option] 

BEGIN 

stringID string 

END 


The STRINGTABLE statement defines one or more string resources for an 
application. String resources are simply null-terminated ASCII strings that can be 
loaded when needed from the executable file, using the LoadString function. 
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The optional load-option field takes a key word that specifies when the resource 
is to be loaded. It must be one of the following: 


Option Description 

PRELOAD Resource is loaded immediately. 

LOADONCALL Resource is loaded when called. This is the default 
option. 


The optional mem-option field takes the following key word or key words, which 
specify whether the resource is fixed or moveable and whether or not it is discard- 


able: 

Option Description 

FIXED . Resource remains at a fixed memory location. 

MOVEABLE Resource can be moved if necessary in order to com- 
pact memory. 

DISCARDABLE Resource can be discarded if no longer needed. 


The default is MOVEABLE and DISCARDABLE. 
The stringID field specifies an integer value that identifies the resource. 


The string field specifies one or more ASCII strings, enclosed in double quota- 
tion marks. The string must be no longer than 255 characters and must occupy a 
single line in the source file. To add a carriage return to the string, use this 
character sequence: \012. For example, “Line one\012Line two” would define a 
string that would be displayed as follows: 


Line one 
Line two 


Grouping strings in separate segments allows all related strings to be read in at 
one time and discarded together. When possible, an application should make the 
table moveable and discardable. The Resource Compiler allocates 16 strings per 
segment and uses the identifier value to determine which segment is to contain 
the string. Strings with the same upper 12 bits in their identifiers are placed in the 
same segment. 


The following example demonstrates the correct usage of the STRINGTABLE 
statement: 


#tdefine IDS_HELLO 1 
#tdefine IDS_GOODBYE 2 


STRINGTABLE 
BEGIN 
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IDS_HELLO, "Hello" 
IDS_GOODBYE, "Goodbye" 
END 
8.5 ACCELERATORS Statement 
Syntax 
acctablename ACCELERATORS 
BEGIN 


event, idvalue, [[type]] [ NOINVERT] [ALT] [SHIFT] [CONTROL] 


END 

The ACCELERATORS statement defines one or more accelerators for an appli- 
cation. An accelerator is a key stroke defined by the application to give the user a 
quick way to perform a task. The TranslateAccelerator function is used to trans- 


late accelerator messages from the application queue into WM_COMMAND or 
WM_SYSCOMMAND messages. 


The acctablename field specifies either a unique name or an integer value that 
identifies the resource. 


The event field specifies the key stroke to be used as an accelerator. It can be any 
one of the following: 


Character Description 


“char” A single ASCII character enclosed in double quotes. 
The character can be preceded by a caret (‘), 
meaning that the character is a control character. 


ASCII character An integer value representing an ASCII character. 
The type field must be ASCII. 


Virtual key character An integer value representing a virtual key. The vir- 
tual key for alphanumeric keys can be specified by 
placing the uppercase letter or number in double quo- 
tation marks (for example, “9” or “C”). The type 
field must be VIRTKEY. 


The idvalue field specifies an integer value that identifies the accelerator. 


The type field is required only when event is an ASCII character or a virtual key 
character. The type field specifies either ASCII or VIRTKEY; the integer value 
of event is interpreted accordingly. When VIRTKEY is specified and the event 
field contains a string, the event field must be uppercase. 
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The NOINVERT option, if given, means that no top-level menu item is 
highlighted when the accelerator is used. This is useful when defining accel- 
erators for actions such as scrolling that do not correspond to a menu item. If 
NOINVERT is omitted, a top-level menu item will be highlighted (if possible) 
when the accelerator is used. 


The ALT option, if given, causes the accelerator to be activated only if the ALT 
key is down. 


The SHIFT option, if given, causes the accelerator to be activated only if the 
SHIFT key is down. 


The CONTROL option, if given, defines the character as a control character (the 
accelerator is only activated if the CONTROL key is down). This has the same ef- 
fect as using a caret (4) before the accelerator character in the event field. 


The ALT, SHIFT, and CONTROL options apply only to virtual keys. 
The following example demonstrates the correct usage of accelerator keys: 


1 ACCELERATORS 


BEGIN 
"ac", IDDCLEAR ; control C 
me IDDCLEAR ; shift K 
TK IDDELLIPSE, ALT ; alt K 
98, IDDRECT, ASCII ; D 
66, IDDSTAR, ASCII ; B (shift b) 
ME" s IDDRECT ; g 
"Ga", IDDSTAR ; G (shift G) 
VK_Fl, IDDCLEAR, VIRTKEY > Fl 
VK_Fl, IDDSTAR, CONTROL, VIRTKEY ; control Fl 
VK_Fl, IDDELLIPSE, SHIFT, VIRTKEY > shift Fl 


VK_F2, IDDCLEAR, ALT, SHIFT, VIRTKEY ; alt shift F2 

VK_F2, IDDSTAR, CONTROL, SHIFT, VIRTKEY ; ctrl shift F2 

VK_F2, IDDRECT, ALT, CONTROL, VIRTKEY ; alt control F2 
END 


8.6 MENU Statement 


Syntax 


menulD MENU [[load-option]] [[{mem-option]] 
BEGIN 

item-definitions 

END 


VK_F1, IDDRECT, ALT, VIRTKEY alt: bd 


The MENU statement defines the contents of a menu resource. A menu resource 
is a collection of information that defines the appearance and function of an appli- 
cation menu. A menu is a special input tool that lets a user select commands from 
a list of command names. 
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The menulD field specifies a name or number used to identify the menu resource. 


The optional /oad-option field takes a key word that specifies when the resource 
is to be loaded. It must be one of the following: 


Option Description 

PRELOAD Resource is loaded immediately. 

LOADONCALL Resource is loaded when called. This is the default 
option. 


The optional mem-option field takes the following key word or key words, which 
specify whether the resource is fixed or moveable and whether it is discardable: 


Option’ Description 

FIXED Resource remains at a fixed memory location. 

MOVEABLE Resource can be moved if necessary in order to com- 
pact memory. 

DISCARDABLE Resource can be discarded if no longer needed. 


The default is MOVEABLE and DISCARDABLE. 


The item-definition field specifies special resource statements that define the 
items in the menu. These statements are defined in the following sections. 


The following is an example of a complete MENU statement: 


sample MENU 
BEGIN 
MENUITEM “&Soup", 188 
MENUITEM "S&alad", 101 
POPUP "&Entree" 
BEGIN 
MENUITEM "&Fish", 200 
MENUITEM "&Chicken", 201, CHECKED 
POPUP "&Beef" 
BEGIN 
MENUITEM "&Steak", 381 
MENUITEM "&Prime Rib", 382 
END 
END 
MENUITEM “&Dessert", 183 
END 
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8.6.1 Iltem-Definition Statements 


The MENUITEM and POPUP statements are used in the item-definition section 
of a MENU statement to define the names and attributes of the actual menu 
items. Any number of statements can be given; each defines a unique item. The 
order of the statements defines the order of the menu items. 


The MENUITEM and POPUP statements can be used only within an item- ae, 
nition section of a MENU statement. 


MENUITEM Statement 


Syntax 
MENUITEM text, result, [optionlist]] 


This optional statement defines a menu item. 


The text field takes an ASCII string, enclosed in double quotation marks, that 
specifies the name of the menu item. 


The string can contain the escape characters \t and \a. The \t character inserts a 
tab in the string and is used to align text in columns. Tab characters should be 
used only in pop-up menus, not in menu bars. (See the following section for infor- 
mation on pop-up menus.) The \a character aligns all text that follows it flush 
right to the menu bar or pop-up menu. 


To insert a double quotation mark (") in the string, use two double quotation 
marks ("""). 


To add a mnemonic to the text string, place the ampersand (&) ahead of the letter 
that will be the mnemonic. This will cause the letter to appear underlined in the 
control and to function as the mnemonic. To use the ampersand as a character in 
a string, insert two ampersands (&&). 


The result field takes an integer value that specifies the result generated when the 
user selects the menu item. Menu-item results are always integers; when the user 
clicks the menu-item name, the result is sent to the window that owns the menu. 


The optional optionlist field takes one or more predefined menu options, sepa- 
rated by commas or spaces, that specify the appearance of the menu item. The 
menu options are as follows: 


Option . Description 
CHECKED Item has a checkmark next to it. 


GRAYED Item name is initially inactive and appears on the 
: menu in gray or a lightened shade of the menu-text 
color. 
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Option Description 
HELP Item has a vertical separator to its left. 
INACTIVE Item name is displayed, but it cannot be selected. 


MENUBARBREAK Same as MF_MENUBREAK except that for pop-up 
menus, it separates the new column from the old 
column with a vertical line. 


MENUBREAK Places the menu item on a new line for static menu- 
bar items. For pop-up menus, places the menu item 
in anew column, with no dividing line between the 
columns. 


The INACTIVE and GRAYED options cannot be used together. 


The following example demonstrates the correct usage of the MENUITEM state- 
ment: 


MENUITEM "“&Alpha", 1, CHECKED, GRAYED 
MENUITEM "&Beta", 2 


POPUP Statement 


Syntax 


POPUP text, [loptionlist] 
BEGIN 

item-definitions 

END 


This statement marks the beginning of the definition of a pop-up menu. A pop-up 
menu (which is also known as a drop-down menu) is a special menu item that dis- 
plays a sublist of menu items when it is selected. 


The text field takes an ASCII string, enclosed in double quotation marks, that 
specifies the name of the pop-up menu. 


The optional optionlist field takes one or more predefined menu options that 
specify the appearance of the menu item. The menu options are as follows: 
Option Description 


CHECKED Item has a checkmark next to it. This option is not 
valid for a top-level pop-up menu. 


GRAYED Item name is initially inactive and appears on the 
menu in gray or a lightened shade of the menu-text 
color. 
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Option Description 
INACTIVE Item name is displayed, but it cannot be selected. 


MENUBARBREAK Same as MF_MENUBREAK except that for pop-up 
menus, it separates the new column from the old 
column with a vertical line. 


MENUBREAK Places the menu item on a new line for static menu- 
bar items. For pop-up menus, places the menu item 
in a new column, with no dividing line between the 
columns. 


The options can be combined using the bitwise OR operator. The INACTIVE 
and GRAYED options cannot be used together. 


The item-definitions field can specify any number of MENUITEM or POPUP 
statements. As a result, any pop-up menu item can display another pop-up menu. 


The following example demonstrates the correct usage of the POPUP statement: 


chem MENU 
BEGIN 


POPUP "&Elements" 

BEGIN 
MENUITEM "&Oxygen", 200 
MENUITEM "&Carbon", 201, CHECKED 
MENUITEM "&Hydrogen", 202 
MENUITEM "&Sulfur", 203 
MENUITEM "Ch&lorine", 204 


END 
POPUP "&Compounds" 
BEGIN 
POPUP "&Sugars" 
BEGIN 
MENUITEM "&Glucose", 301 
MENUITEM "&Sucrose", 302, CHECKED 
MENUITEM "&Lactose", 383, MENUBREAK 
’ MENUITEM "&Fructose", 304 
END 


POPUP "&Acids" 

BEGIN 
"&Hydrochloric", 401 
"&Sulfuric", 42 

END 


END 


END 
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MENUITEM SEPARATOR Statement 


Syntax 
MENUITEM SEPARATOR 


This special form of the MENUITEM statement creates an inactive menu item 
that serves as a dividing bar between two active menu items in a pop-up menu. 


The following demonstrates the correct usage of the MENUITEM SEPARA- 
TOR statement: 


MENUITEM "&Roman", 206 
MENUITEM SEPARATOR 
MENUITEM "&2@ Point", 301 


8.7 DIALOG Statement 


The DIALOG statement defines a template that can be used by an application to 
create dialog boxes. 


Syntax 


nameID DIALOG [[load-option]] [[mem-option]] x, y, width, height 
[loption-statements]] 

BEGIN 

control-statements 

END 


This statement marks the beginning of a DIALOG template. It defines the name 
of the dialog box, the memory and load options, the box’s starting location on the 
display screen, and the box’s width and height. 


The namelD field specifies either a unique name or an integer value that identi- 
fies the resource. 


The optional /oad-option field takes a key word that specifies when the resource 
is to be loaded. It must be one of the following: 


Option Description 

PRELOAD Resource is loaded immediately. 

LOADONCALL Resource is loaded when called. This is the default 
option. 


The optional mem-option field takes the following key word or key words, which 
specify whether the resource is fixed or moveable and whether it is discardable: 
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Option Description 

FIXED Resource remains at a fixed memory location. 

MOVEABLE Resource can be moved if necessary in order to com- 
pact memory. This is the default option. 

DISCARDABLE Resource can be discarded if no longer needed. 


The x and y fields take integer values that specify the x and y coordinates of the 
upper-left corner of the dialog box. The horizontal units are 14 of the dialog base 
width unit; the vertical units are 1 of the dialog base height unit. The current 
dialog base units are computed from the height and width of the current system 
font. The GetDialogBaseUnits function returns the dialog base units in pixels. 
The exact meaning of the coordinates depends on the style defined by the 
STYLE option statement. For child-style dialog boxes, the coordinates are rela- 
tive to the origin of the parent window, unless the dialog box has the style 
DS_ABSALIGN;; in that case, the coordinates are relative to the origin of the dis- 
play screen. 


The width and height fields take integer values that specify the width and height 
of the box. The width units are 14 of the dialog base width unit; the height units 
are 1% of the dialog base height unit. 


The option and control statements are described in the following sections. 
The following demonstrates the correct usage of the DIALOG statement: 
#Hinclude "WINDOWS.H" 


errmess DIALOG 10, 10, 300, 110 

STYLE WS_POPUP|WS_BORDER 

CAPTION "Error!" 

BEGIN 
CTEXT “Select One:", 1, 18, 10, 280, 12 
RADIOBUTTON "&Retry", 2, 75, 38, 68, 12 
RADIOBUTTON "&Abort", 3, 75, 58, 68, 12 
RADIOBUTTON "&Ignore", 4, 75, 88, 60, 12 

END 


Comments 


Do not use the WS_CHILD style with a modal dialog box. The DialogBox func- 
tion always disables the parent/owner of the newly-created dialog box. When a 
parent window is disabled, its child windows are implicitly disabled. Since the 
parent window of the child-style dialog box is disabled, the child-style dialog 
box is too. 


If a dialog box has the DS_ABSALIGN style, the dialog coordinates for its 
upper-left corner are relative to the screen origin instead of to the upper-left 
comer of the parent window. You would typically use this style when you 
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wanted the dialog box to start in a specific part of the display no matter where the 
parent window may be on the screen. 


The name DIALOG can also be used as the class-name parameter to the 
CreateWindow function in order to create a window with dialog-box attributes. 


8.7.1 Dialog Option Statements 


The dialog option statements, given in the option-statements section of the 
DIALOG statement, define special attributes of the dialog box, such as its style, 
caption, and menu. The option statements are optional. If the application does not 
supply a particular option statement, the dialog box is given default attributes for 
that option. Dialog option statements include the following: 

= STYLE 

= CAPTION 

=» MENU 

= CLASS 


= FONT 


The option statements are discussed individually in the following sections. 


STYLE Statement 


Syntax 
STYLE style 


This optional statement defines the window style of the dialog box. The window 
style specifies whether the box is a pop-up or a child window. The default style 
has the following attributes: 


WS_POPUP 
WS_BORDER 
WS_SYSMENU 


The style field takes an integer value or predefined name that specifies the 
window style. It can be any of the window styles defined in Table 8.1, “Window 
Styles.” 


Comments 


If the predefined names are used, the #include directive must be used so that the 
WINDOWS-H file will be included in the resource script. 
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Table 8.1 Window Styles 
Style 


DS_LOCALEDIT 


DS_MODALFRAME 


DS_NOIDLEMSG 


DS_SYSMODAL 
WS_BORDER 
WS_CAPTION 


WS_CHILD 
WS_CHILDWINDOW 


WS_CLIPCHILDREN 


WS_CLIPSIBLINGS 


WS_DISABLED 
WS_DLGFRAME 


Meaning 


Specifies that edit controls in the dialog box will 
use memory in the application’s data segment. By 
default, all edit controls in dialog boxes use 
memory outside the application’s data segment. 
This feature can be suppressed by adding the 
DS_LOCALEDIT flag to the STYLE command 
for the dialog box. If this flag is not used, 
EM_GETHANDLE and EM_SETHANDLE mes- 
sages must not be used since the storage for the 
control is not in the application’s data segment. 
This feature does not affect edit controls created 
outside of dialog boxes. 


Creates a dialog box with a modal dialog-box 
frame that can be combined with a title bar and 
system menu by specifying the WS_CAPTION 
and WS_SYSMENU styles. 


Suppresses WM_ENTERIDLE messages that 
Windows would otherwise send to the owner of 
the dialog box while the dialog box is displayed. 


Creates a system-modal dialog box. 
Creates a window that has a border. 


Creates a window that has a title bar (implies 
WS_BORDER). 


Creates a child window. It cannot be used with 
WS_POPUP. 


Creates a child window that has the style 
WS_CHILD. 


Excludes the area occupied by child windows 
when drawing within the parent window. Used 
when creating the parent window. 


Clips child windows relative to each other; that is, 
when a particular child window receives a 
WP_PAINT message, this style clips all other top- 
level child windows out of the region of the child 
window to be updated. (If WS_CLIPSIBLINGS is 
not given and child windows overlap, it is 
possible, when drawing in the client area of a 
child window, to draw in the client area of a neigh- 
boring child window.) For use with WS_CHILD 
only. 


Creates a window that is initially disabled. 


Creates a window with a modal dialog-box frame 
but no title. 
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Style 


WS_GROUP 


WS_HSCROLL 
WS_ICONIC 


WS_MAXIMIZE 
WS_MAXIMIZEBOX 
WS_MINIMIZE 
WS_MINIMIZEBOX 
WS_OVERLAPPED 


WS_OVERLAPPEDWINDOW 


WS_POPUP 


WS_POPUPWINDOW 


WS_SIZEBOX 


WS_SYSMENU 


WS_TABSTOP 
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Window Styles (continued) 


Meaning 


Specifies the first control of a group of controls in 
which the user can move from one control to the 
next by using the arrow keys. All controls defined 
with the WS_GROUP style after the first control 
belong to the same group. The next control with 
the WS_GROUP style ends the style group and 
starts the next group (i.e., one group ends where 
the next begins). This style is valid only for con- 
trols. 


Creates a window that has a horizontal scroll bar. 


Creates a window that is initially iconic. For use 
with WS_OVERLAPPED only. 


Creates a window of maximum size. 
Creates a window that has a Maximize box. 
Creates a window of minimum size. 
Creates a window that has a Minimize box. 


Creates an overlapped window. An overlapped 
window has a caption and a border. 


Creates an overlapped window having the 
WS_OVERLAPPED, WS_CAPTION, WS_SYS- 
MENU, WS_THICKFRAME, 
WS_MINIMIZEBOX, and WS_MAXIMIZE- 
BOX styles. 


Creates a pop-up window. It cannot be used with 
WS_CHILD. 


Creates a pop-up window that has the styles 
WS_POPUP, WS_BORDER, and WS_SYS- 
MENU. The WS_CAPTION style must be 
combined with the WS_POPUPWINDOW style 
to make the system menu visible. 


Creates a window that has a size box. Used only 
for windows with a title bar or with vertical and 
horizontal scroll bars. 


Creates a window that has a System-menu box in 
its title bar. Used only for windows with title bars. 
If used with a child window, this style creates a 
Close box instead of a System-menu box. 


Specifies one of any number of controls through 
which the user can move by using the TAB key. 
The TAB key moves the user to the next control 
specified by the WS_TABSTOP style. This style 
is valid only for controls. 
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Table 8.1 Window Styles (continued) 


Style Meaning 

WS_THICKFRAME Creates a window with a thick frame that can be 
used to size the window. 

WS_VISIBLE Creates a window that is initially visible. This ap- 


plies to overlapping and pop-up windows. For 
overlapping windows, the y parameter is used as a 
Show Window function parameter. 


WS_VSCROLL Creates a window that has a vertical scroll bar. 


CAPTION Statement 


Syntax 
CAPTION captiontext 


This optional statement defines the dialog box’s title. The title appears in the 
box’s caption bar (if it has one). 


The default caption is empty. 


The captiontext field specifies an ASCII character string enclosed in double quo- 
tation marks. 


The following example demonstrates the correct usage of the CAPTION state- 
ment: 


CAPTION "Error!" 


MENU Statement 


Syntax 
MENU menuname 


This optional statement defines the dialog box’s menu. If no statement is given, 
the dialog box has no menu. 


The menuname field specifies the resource name or number of the menu to be 
used. 


The following example demonstrates the correct usage of the MENU statement: 


MENU errmenu 
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CLASS Statement 


Syntax 
CLASS class 


This optional statement defines the class of the dialog box. If no statement is 
given, the Windows standard dialog class will be used as the default. 


The class field specifies an integer or a string, enclosed in double quotation 
marks, that identifies the class of the dialog box. If the window procedure for the 
class does not process a message sent to it, it must call the DefDlgProc function 
to ensure that all messages are handled properly for the dialog box. A private 
class can use DefDIgProc as the default window procedure. The class must be 
registered with the cbWndExtra field of the WNDCLASS data structure set to 
DLGWINDOWEXTRA. 


The following example demonstrates the correct usage of the CLASS statement: 


CLASS "myclass” 


Comments 


The CLASS statement should be used with special cases, since it overrides the 
normal processing of a dialog box. The CLASS statement converts a dialog box 
to a window of the specified class; depending on the class, this could give un- 
desirable results. Do not use the predefined control class names with this state- 
ment. 


FONT Statement 


Syntax 
FONT pointsize, typeface 


This optional statement defines the font with which Windows will draw text in 
the dialog box. The font must have been previously loaded, either from WIN.INI 
or by calling LoadFont. 


The pointsize field is an integer that specifies the size in points of the font. 


The typeface field specifies an ASCII character string enclosed in double quota- 
tion marks that specifies the name of the typeface. This name must be identical to 
the name defined in the [fonts] section of WIN.INI. 


The following example demonstrates the correct usage of the FONT statement: 


FONT 12, "Helv" 
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8.7.2 Dialog Control Statements 


The dialog control statements, given in the control-statements section of the 
DIALOG statement, define the attributes of the control windows that appear in 
the dialog box. A dialog box is empty unless one or more control statements are 
given. Control statements include the following: 


= LTEXT 

= RTEXT 

= CTEXT 

=» CHECKBOX 

as PUSHBUTTON 

a LISTBOX 

=» GROUPBOX 

xs DEFPUSHBUTTON 
=» RADIOBUTTON 

m EDITTEXT 

=» COMBOBOX 

m ICON 

=» SCROLLBAR 

=» CONTROL 

The control statements are discussed individually in the following sections. For 


more information on control classes and styles, see Tables 8.2, “Control 
Classes,” and 8.3, “Control Styles.” 


LTEXT Statement 


Syntax 
LTEXT text, id, x, y, width, height, [[style]] 


This statement defines a flush-left text control. It creates a simple rectangle that 
displays the given text flush-left in the rectangle. The text is formatted before it is 
displayed. Words that would extend past the end of a line are automatically 
wrapped to the beginning of the next line. 


The text field takes an ASCII string that specifies the text to be displayed. The 
string must be enclosed in double quotation marks. To add a mnemonic to the 
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text string, place the ampersand (&) ahead of the letter that will be the mne- 
monic. To use the ampersand as a character in a string, insert two ampersands 
(&&). 


The id field takes a unique integer value that identifies the control. 


The x and y fields take integer values that specify the x and y coordinates of the 
upper-left corner of the control. The horizontal units are 14 of the dialog base 
width unit; the vertical units are 1 of the dialog base height unit. The current 
dialog base units are computed from the height and width of the current system 
font. The GetDialogBaseUnits function returns the dialog base units in pixels. 
The coordinates are relative to the origin of the dialog box. 


The width and height fields take integer values that specify the width and height 
of the control. The width units are 4 of the dialog base width unit; the height. 
units are 1 of the dialog base height unit. 


The optional style field can contain any combination (or none) of the following 
styles: 

= WS_TABSTOP 

= WS_GROUP 


These styles are described in Table 8.1, “Window Styles.” Styles can be com- 
bined using the bitwise OR operator. 


Comments 


The x, y, width, and height fields can use the addition operator (+) for relative 
positioning. For example, “15 + 6” can be used for the x field. 


The default style for LTEXT is SS_LEFT and WS_GROUP. 
The following example demonstrates the correct usage of the LTEXT statement: 


LTEXT “Enter Name:", 3, 10, 10, 40, 10 


RTEXT Statement 


Syntax | 
RTEXT text, id, x, y, width, height, {[style]] 


This statement defines a flush-right text control. It creates a simple rectangle that 
displays the given text flush-right in the rectangle. The text is formatted before it 
is displayed. Words that would extend past the end of a line are automatically 
wrapped to the beginning of the next line. 


The text field takes an ASCII string that specifies the text to be displayed. The 
string must be enclosed in double quotation marks. To add a mnemonic to the 
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text string, place the ampersand (&) ahead of the letter that will be the mne- 
monic. To use the ampersand as a character in a string, insert two ampersands 
(&&). 


The id field takes a unique integer value that identifies the control. 


The x and y fields take integer values that specify the x and y coordinates of the 
upper-left corner of the control. The horizontal units are 4 of the dialog base 
width unit; the vertical units are !4 of the dialog base height unit. The current 
dialog base units are computed from the height and width of the current system 
font. The GetDialogBaseUnits function returns the dialog base units in pixels. 
The coordinates are relative to the origin of the dialog box. 


The width and height fields take integer values that specify the width and height 
of the control. The width units are 14 of the dialog base width unit; the height 
units are 1% of the dialog base height unit. 


The optional style field can contain any combination (or none) of the following | 
styles: 

= WS_TABSTOP 

= WS_GROUP 


These styles are described in Table 8.1, “Window Styles.” Styles can be com- 
bined using the bitwise OR operator. 


Comments 


The x, y, width, and height fields can use the addition operator (+) for relative 
positioning. For example, “15 + 6” can be used for the x field. 


The default style for RTEXT is SS_RIGHT and WS_GROUP. 
The following example demonstrates the correct usage of the RTEXT statement: 


RTEXT "Number of Messages", 4, 38, 58, 108, 10 


CTEXT Statement 


Syntax 
CTEXT text, id, x, y, width, height, [[style]] 


This statement defines a centered text control. It creates a simple rectangle that 
displays the given text centered in the rectangle. The text is formatted before it is 
displayed. Words that would extend past the end of a line are automatically 
wrapped to the beginning of the next line. 


The text field takes an ASCII string that specifies the text to be displayed. The 
string must be enclosed in double quotation marks. To add a mnemonic to the 
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text string, place the ampersand (&) ahead of the letter that will be the mne- 
monic. To use the ampersand as a character in a string, insert two ampersands 
(&&). 


The id field takes a unique integer value that identifies the control. 


The x and y fields take integer values that specify the x and y coordinates of the 
upper-left corner of the control. The horizontal units are 4 of the dialog base 
width unit; the vertical units are !/g of the dialog base height unit. The current 
dialog base units are computed from the height and width of the current system 
font. The GetDialogBaseUnits function returns the dialog base units in pixels. 
The coordinates are relative to the origin of the dialog box. 


The width and height fields take integer values that specify the width and height 
of the control. The width units are 4 of the dialog base width unit; the height 
units are | of the dialog base height unit. 


The optional style field can contain any combination (or none) of the following 
styles: 

gs WS_TABSTOP 

m =WS_GROUP 


These styles are described in Table 8.1, “Window Styles.” Styles can be com- 
bined using the bitwise OR operator. 


Comments 


The x, y, width, and height fields can use the addition operator (+) for relative 
positioning. For example, “15 + 6” can be used for the x field. 


The default style for CTEXT is SS_CENTER and WS_GROUP. 
The following example demonstrates the correct usage of the CTEXT statement: 


CTEXT "Title", 3, 10,. 58, 40, 10 


CHECKBOX Statement 


Syntax 
CHECKBOX text, id, x, y, width, height, [[style]] 


This statement defines a check-box control belonging to the BUTTON class. It 
creates a small rectangle (check box) that is highlighted when clicked. The given 
text is displayed just to the right of the check box. The control highlights the 
rectangle when the user clicks the mouse in it, and removes the highlight on the 
next click. 
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The text field takes an ASCII string that specifies the text to be displayed. The 
string must be enclosed in double quotation marks. To add a mnemonic to the 
text string, place the ampersand (&) ahead of the letter that will be the mne- 
monic. To use the ampersand as a character in a string, insert two ampersands 
(&&). 


The id field takes a unique integer value that identifies the control. 


The x and y fields take integer values that specify the x and y coordinates of the 
upper-left corner of the control. The horizontal units are 4 of the dialog base 
width unit; the vertical units are !4 of the dialog base height unit. The current 
dialog base units are computed from the height and width of the current system 
font. The GetDialogBaseUnits function returns the dialog base units in pixels. 
The coordinates are relative to the origin of the dialog box. 


The width and height fields take integer values that specify the width and height 
of the control. The width units are 14 of the dialog base width unit; the height 
units are 1 of the dialog base height unit. 


The optional style field can contain any combination (or none) of the following 
styles: 

= WS_TABSTOP 

= WS _ GROUP 


These styles are described in Table 8.1, “Window Styles.” 


In addition to these styles, the style field may contain any combination (or none) 
of the BUTTON-class styles described in Table 8.3, “Control Styles.” Styles can 
be combined using the bitwise OR operator. 


Comments 


The x, y, width, and height fields can use the addition operator (+) for relative 
positioning. For example, “15 + 6” can be used for the x field. 


The default style for CHECKBOX is BS_CHECKBOX and WS_TABSTOP. ' 


The following example demonstrates the correct usage of the CHECKBOX 
statement: 


CHECKBOX "Arabic", 3, 10, 10, 40, 10 
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PUSHBUTTON Statement 


Syntax | 
PUSHBUTTON text, id, x, y, width, height, ([style]] 


This statement defines a push-button control belonging to the BUTTON class. It 
creates a rectangle containing the given text. The control sends a message to its 
parent whenever the user clicks the mouse inside the rectangle. 


The text field takes an ASCII string that specifies the text to be displayed. The 
string must be enclosed in double quotation marks. To add a mnemonic to the 
text string, place the ampersand (&) ahead of the letter that will be the mne- 
monic. To use the ampersand as a character in a string, insert two ampersands 
(&&). 


The id field takes a unique integer value that identifies the control. 


The x and y fields take integer values that specify the x and y coordinates of the 
upper-left corner of the control. The horizontal units are 4 of the dialog base 
width unit; the vertical units are 1 of the dialog base height unit. The current 
dialog base units are computed from the height and width of the current system 
font. The GetDialogBaseUnits function returns the dialog base units in pixels. 
The coordinates are relative to the origin of the dialog box. 


The width and height fields take integer values that specify the width and height 
of the control. The width units are 1 of the dialog base width unit; the height 
units are 1% of the dialog base height unit. 


The optional style field can contain any combination (or none) of the following 
styles: 

= WS_TABSTOP 

=» WS_DISABLED 

= WS_GROUP 


These styles are described in Table 8.1, “Window Styles.” 


In addition to these styles, the style field may contain any combination (or none) 
of the BUTTON-class styles described in Table 8.3, “Control Styles.” Styles can 
be combined using the bitwise OR operator. 


Comments 


The x, y, width, and height fields can use the addition operator (+) for relative 
positioning. For example, “15 + 6” can be used for the x field. 


The default style for PUSHBUTTON is BS_PUSHBUTTON and WS_TAB- 
STOP. 
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The following example demonstrates the correct usage of the PUSHBUTTON 
statement: 


PUSHBUTTON "ON", 7, 10, 10, 20, 19 


LISTBOX Statement 


Syntax - 
LISTBOX id, x, y, width, height, [[style]] 


This statement defines a list box belonging to the LISTBOX class. It creates a 
rectangle that contains a list of strings (such as filenames) from which the user 
can make selections. 


The id field takes a unique integer value that identifies the control. 


The x and y fields take integer values that specify the x and y coordinates of the 
upper-left corner of the control. The horizontal units are 14 of the dialog base 
width unit; the vertical units are 14 of the dialog base height unit. The current 
dialog base units are computed from the height and width of the current system 
font. The GetDialogBaseUnits function returns the dialog base units in pixels. 
The coordinates are relative to the origin of the dialog box. 


The width and height fields take integer values that specify the width and height 
of the control. The width units are 14 of the dialog base width unit; the height 
units are 1% of the dialog base height unit. 


The optional style field can contain any combination (or none) of the following 
styles: 

= WS_BORDER 

= WS_VSCROLL 


These styles are described in Table 8.1, “Window Styles.” 


In addition to these styles, the style field may contain any combination (or none) 
of the LISTBOX-class styles described in Table 8.3, “Control Styles.” Styles can 
be combined using the bitwise OR operator. 


Comments 


The x, y, width, and height fields can use the addition operator (+) for relative 
positioning. For example, “15 + 6” can be used for the x field. 


The default style for LISTBOX is LBS_NOTIFY, WS_VSCROLL, and 
WS_BORDER. 
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For information on the recommended keys for use in list-box controls, see the 
System Application Architecture, Common User Access: Advanced Interface 
Design Guide. 


The following example demonstrates the correct usage of the LISTBOX 
statement: 


LISTBOX 666, 18, 10, 58, 54 


GROUPBOX Statement 


Syntax 
GROUPBOX text, id, x, y, width, height, [[style]] 


This statement defines a group box belonging to the BUTTON class. It creates a 
rectangle that groups other controls together. The controls are grouped by draw- 
ing a border around them and displaying the given text in the upper-left corner. 


The fext field takes an ASCII string that specifies the text to be displayed. The 
string must be enclosed in double quotation marks. To add a mnemonic to the 
text string, place the ampersand (&) ahead of the letter that will be the mne- 
monic. Selecting the mnemonic moves the input focus to the next control in the 
group, in the order set in the resource file. To use the ampersand as a character in 
a string, insert two ampersands (&&). 


The id field takes a unique integer value that identifies the control. 


The x and y fields take integer values that specify the x and y coordinates of the 
upper-left corner of the control. The horizontal units are /% of the dialog base 
width unit; the vertical units are 1 of the dialog base height unit. The current 
dialog base units are computed from the height and width of the current system 
font. The GetDialogBaseUnits function returns the dialog base units in pixels. 
The coordinates are relative to the origin of the dialog box. 


The width and height fields take integer values that specify the width and height 
of the control. The width units are 4 of the dialog base width unit; the height 
units are 4 of the dialog base height unit. 


The optional style field can contain any combination (or none) of the following 
styles: 


= WS_TABSTOP 
=» WS_DISABLED 


These styles are described in Table 8.1, “Window Styles.” 


In addition to these styles, the style field may contain any combination (or none) 
of the BUTTON-class styles described in Table 8.3, “Control Styles.” Styles can 
be combined using the bitwise OR operator. 
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Comments 


The x, y, width, and height fields can use the addition operator (+) for relative 
positioning. For example, “15 + 6” can be used for the x field. 


The default style for GROUPBOX is BS_GROUPBOX and WS_TABSTOP. 


The following example demonstrates the correct usage of the GROUPBOX state- 
ment: 


GROUPBOX "Output", 42, 10, 19, 30, 5B 


DEFPUSHBUTTON Statement 


Syntax 
DEFPUSHBUTTON text, id, x, y, width, height, [[style]] 


This statement defines a default push-button control that belongs to the 
BUTTON class. It creates a small rectangle with a bold outline that represents 
the default response for the user. The given text is displayed inside the button. 
The control highlights the button in the usual way when the user clicks the mouse 
in it and sends a message to its parent window. 


The text field takes an ASCII string that specifies the text to be displayed. The 
string must be enclosed in double quotation marks. To add a mnemonic to the 
text string, place the ampersand (&) ahead of the letter that will be the mne- 
monic. To use the ampersand as a character in a string, insert two ampersands 
(&&). 


The id field takes a unique integer value that identifies the control. 


The x and y fields take integer values that specify the x and y coordinates of the 
upper-left corner of the control. The horizontal units are 4 of the dialog base 
width unit; the vertical units are ! of the dialog base height unit. The current 
dialog base units are computed from the height and width of the current system 
font. The GetDialogBaseUnits function returns the dialog base units in pixels. 
The coordinates are relative to the origin of the dialog box. 


The width and height fields take integer values that specify the width and height 
of the control. The width units are 4 of the dialog base width unit; the height 
units are 18 of the dialog base height unit. 


The optional style field can contain any combination (or none) of the following 
styles: 


= WS_TABSTOP 
= WS _GROUP 
# WS_DISABLED 
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These styles are described in Table 8.1, “Window Styles.” 


In addition to these styles, the style field may contain any combination (or none) 
of the BUTTON-class styles described in Table 8.3, “Control Styles.” Styles can 
be combined using the bitwise OR operator. 


Comments 


The x, y, width, and height fields can use the addition operator (+) for relative 
positioning. For example, “15 + 6” can be used for the x field. 


The default style for DEFPUSHBUTTON is BS_DEFPUSHBUTTON and 
WS_TABSTOP. 


The following example demonstrates the correct usage of the DEFPUSH- 
BUTTON statement: 


DEFPUSHBUTTON "ON", 7, 10, 10, 20, 10 


RADIOBUTTON Statement 


Syntax 
RADIOBUTTON text, id, x, y, width, height, [[style]] 


This statement defines a radio-button control belonging to the BUTTON class, It 

creates a small circle that has the given text displayed just to its right. The control 
highlights the button when the user clicks the mouse in it and sends a message to 

its parent window. The control removes the highlight and sends a message on the 
next click. 


The text field takes an ASCII string that specifies the text to be displayed. The 
string must be enclosed in double quotation marks. To add a mnemonic to the 
text string, place the ampersand (&) ahead of the letter that will be the mne- 
monic. To use the ampersand as a character in a string, insert two ampersands 
(&&). 


The id field takes a unique integer value that identifies the control. 


The x and y fields take integer values that specify the x and y coordinates of the 
upper-left corner of the control. The horizontal units are 1 of the dialog base 
width unit; the vertical units are 1 of the dialog base height unit. The current 
dialog base units are computed from the height and width of the current system 
font. The GetDialogBaseUnits function returns the dialog base units in pixels. 
The coordinates are relative to the origin of the dialog box. 


The width and height fields take integer values that specify the width and height 
of the control. The width units are 14 of the dialog base width unit; the height 
units are 8 of the dialog base height unit. 


The optional style field can contain any combination (or none) of the following 
styles: 
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=» WS_TABSTOP 
= WS_GROUP 
= WS_DISABLED 


These styles are described in Table 8.1, “Window Styles.” 


In addition to these styles, the style field may contain any combination (or none) 
of the BUTTON-class styles described in Table 8.3, “Control Styles.” Styles can 
be combined using the bitwise OR operator. 


Comments 


The x, y, width, and height fields can use the addition operator (+) for relative 
positioning. For example, “15 + 6” can be used for the x field. 


The default style for RADIOBUTTON is BS_ RADIOBUTTON and WS_TAB- 
STOP. . 


The following example demonstrates the correct usage of the RADIOBUTTON 
statement: 


RADIOBUTTON "AM 181", 10, 18, 10, 48, 10 


EDITTEXT Statement 


Syntax 
EDITTEXT id, x, y, width, height, [[style]] 


This statement defines an EDIT control belonging to the EDIT class. It creates a 
rectangular region in which the user can enter and edit text. The control displays 
a cursor when the user clicks the mouse in it. The user can then use the keyboard 
to enter text or edit the existing text. Editing keys include the BACKSPACE and 
DELETE keys. The user can also use the mouse to select characters to be deleted, 
or to select the place to insert new characters. 


The id field takes a unique integer value that identifies the control. 


The x and y fields take integer values that specify the x and y coordinates of the 
upper-left corner of the control. The horizontal units are 4 of the dialog base 
width unit; the vertical units are 1% of the dialog base height unit. The current 
dialog base units are computed from the height and width of the current system 
font. The GetDialogBaseUnits function returns the dialog base units in pixels. 
The coordinates are relative to the origin of the dialog box. 


The width and height fields take integer values that specify the width and height 
of the control. The width units are 14 of the dialog base width unit; the height 
units are 1 of the dialog base height unit. 


Resource Script Statements 8-31 
SE a eee ae ee eee eee ee 


The optional style field can contain any combination (or none) of the following 
styles: 

= WS_TABSTOP 

= WS_GROUP 

m WS_VSCROLL 

= WS_HSCROLL 

= WS_DISABLED 


These styles are described in Table 8.1, “Window Styles.” 


In addition.to these styles, the style field may contain any combination (or none) 
of the EDIT-class styles described in Table 8.3, “Control Styles.” Styles can be 
combined using the bitwise OR operator. The EDIT-class styles must not conflict 
with each other. 


Comments 
The x, y, width, and height fields can use the addition operator (+) for relative 
positioning. For example, “15 + 6” can be used for the x field. 


The default style for EDITTEXT is WS_TABSTOP, ES_LEFT, and 
WS_BORDER. 


Keyboard use is predefined for edit controls. Predefined keys are listed in the Sys- 
tem Application Architecture, Common User Access: Advanced Interface Design 
Guide. 


The following example demonstrates the correct usage of the EDITTEXT 
statement: 


EDITTEXT 3, 18, 10, 100, 18 


COMBOBOX Statement 


Syntax 
COMBOBOX id, x, y, width, height, [[style]] 


This statement defines a combo box belonging to the COMBOBOxX< class. A 
combo box consists of either a static text field or edit field combined with a list 
box. The list box can be displayed at all times or pulled down by the user. If the 
combo box contains a static text field, the text field always displays the selection 
(if any) in the list-box portion of the combo box. If it uses an edit field, the user 
can type in the desired selection; the list box highlights the first item (if any) 
which matches what the user has entered in the edit field. The user can then 


8-32 Reference — Volume 2 


select the item highlighted in the list box to complete the choice. In addition, the 
combo box can be owner-draw and of fixed or variable height. 


The id field takes a unique integer value that identifies the control. 


The x and y fields take integer values that specify the x and y coordinates of the 
upper-left corner of the control. The horizontal units are 4 of the dialog base 
width unit; the vertical units are 8 of the dialog base height unit. The current 
dialog base units are computed from the height and width of the current system 
font. The GetDialogBaseUnits function returns the dialog base units in pixels. 
The coordinates are relative to the origin of the dialog box. 


The width and height fields take integer values that specify the width and height 
of the control. The width units are 1% of the dialog base width unit; the height 
units are ¥8 of the dialog base height unit. 


The optional style field can contain any combination (or none) of the following 
styles: 

= WS_TABSTOP 

= WS_GROUP 

= WS_VSCROLL 

= WS_DISABLED 


These styles are described in Table 8.1, ““Window Styles.” 


In addition to these styles, the style field may contain any combination (or none) 
of the combo-box styles described in Table 8.3, “Control Styles.” Styles can be 
combined using the bitwise OR operator. 


Comments 


The x, y, width, and height fields can use the addition operator (+) for relative 
positioning. For example, “15 + 6” can be used for the x field. 


The default style for COMBOBOX is WS_TABSTOP and CBS_SIMPLE. 


For information on the recommended keys for use in combo-box controls, see the 
System Application Architecture, Common User Access: Advanced Interface De- 
sign Guide. 


The following example demonstrates the correct usage of the COMBOBOX 
statement: 


COMBOBOX 777, 18, 10, 50, 54, CBS_SIMPLE | WS_VSCROLL | WS_TABSTOP 
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ICON Statement 


Syntax 
ICON text, id, x, y, width, height, [[style]] 


This statement defines an icon control belonging to the STATIC class. It creates 
an icon displayed in the dialog box. 


The text field specifies the name of an icon (not a filename) defined elsewhere in 
the resource file. 


The id field takes a unique integer value that identifies the control. 


The x and y fields take integer values that specify the x and y coordinates of the 
upper-left corner of the control. The horizontal units are % of the dialog base 
width unit; the vertical units are 1 of the dialog base height unit. The current 
dialog base units are computed from the height and width of the current system 
font. The GetDialogBaseUnits function returns the dialog base units in pixels. 
The coordinates are relative to the origin of the dialog box. 


For the ICON statement, the width and height fields are ignored; the icon auto- 
matically sizes itself. 


The optional style field allows only the SS_ICON style. 


Comments 


The x, y, width, and height fields can use the addition operator (+) for relative 
positioning. For example, “15 + 6” can be used for the x field. . 


The default style for ICON is SS_ICON. 
The following example demonstrates the correct usage of the ICON statement: 


ICON "myicon" 981, 38, 30 


SCROLLBAR Statement 


Syntax 
SCROLLBAR id, x, y, width, height, [[style]] 


This statement defines a scroll-bar control belonging to the SCROLLBAR class. 
It is a rectangle that contains a scroll thumb and has direction arrows at both 
ends. The scroll-bar control sends a notification message to its parent whenever 
the user clicks the mouse in the control. The parent is responsible for updating 
the thumb position. Scroll-bar controls can be positioned anywhere in a window 
and used whenever needed to provide scrolling input. 


The id field takes a unique integer value that identifies the control. 


8-34 Reference — Volume 2 


The x and y fields take integer values that specify the location of the upper-left 
comer of the control in dialog units relative to the origin of the dialog box. The 
horizontal units are 1/4 of the dialog base width unit; the vertical units are 1 of 
the dialog base height unit. The current dialog base units are computed from the 
height and width of the current system font. The GetDialogBaseUnits function 
returns the dialog base units in pixels. 


The width and height fields take integer values that specify the width and height 
of the control. The width units are 4 of the dialog base width unit; the height 
units are 1 of the dialog base height unit. 


The optional style field can contain any combination (or none) of the following 
styles: 

= WS_TABSTOP 

= WS_GROUP 

= WS_DISABLED 


These styles are described in Table 8.1, “Window Styles.” 


In addition to these styles, the style field may contain any combination (or none) 
of the SCROLLBAR-class styles described in Table 8.3, “Control Styles.” Styles 
can be combined using the bitwise OR operator. 


Comments 


The x, y, width, and height fields can use the addition operator (+) for relative 
positioning. For example, “15 + 6” can be used for the x field. 


The default style for SCROLLBAR is SBS_HORZ. 


The following example demonstrates the correct usage of the SCROLLBAR 
statement: 


SCROLLBAR 999, 25, 30, 10, 180 


CONTROL Statement 


Syntax 
CONTROL text, id, class, style, x, y, width, height 
This statement defines a user-defined control window. 


The text field takes an ASCII string that specifies the text to be displayed. The 
string must be enclosed in double quotation marks. 


The id field takes a unique integer value that identifies the control. 
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The class field takes a predefined name, character string, or integer value that de- 
fines the class. This can be any one of the control classes; for a list of the control 
classes, see Table 8.2, “Control Classes.” If the value is a predefined name sup- 
plied by the application, it must be an ASCII string enclosed in double quotation 
marks. 


The style field takes a predefined name or integer value that specifies the style of 
the given control. The exact meaning of style depends on the class value. Tables 
8.2, “Control Classes,” and 8.3, “Control Styles,” list the control classes and 
corresponding styles. 


The x and y fields take integer values that specify the x and y coordinates of the 
upper-left corner of the control. The horizontal units are 14 of the dialog base 
width unit; the vertical units are 1 of the dialog base height unit. The current 
dialog base units are computed from the height and width of the current system 
font. The GetDialogBaseUnits function returns the dialog base units in pixels. 
The coordinates are relative to the origin of the dialog box. 


The width and height fields take integer values that specify the width and height 
of the control. The width units are 4 of the dialog base width unit; the height 
units are 14 of the dialog base height unit. 


Comments 


The x, y, width, and height fields can use the addition operator (+) for relative 
positioning. For example, “15 + 6” can be used for the x field. 


Table 8.2 describes the six control classes: 


Table 8.2 Control Classes 


Class Description 


BUTTON A button control is a small rectangular child window that repre- 
sents a “button” that the user can turn on or off by clicking it 
with the mouse. Button controls can be used alone or in groups, 
and can either be labeled or appear without text. Button con- 
trols typically change appearance when the user clicks them. 


COMBOBOX Combo-box controls consist of a selection field similar to an 
edit control plus a list box. The list box may be displayed at all 
times or may be dropped down when the user selects a “pop 
box” next to the selection field. 


Depending on the style of the combo box, the user can or can- 
not edit the contents of the selection field. If the list box is 
visible, typing characters into the selection box will cause the 
first list box entry which matches the characters typed to be 
highlighted. Conversely, selecting an item in the list box dis- 
plays the selected text in the selection field. 
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Table 8.2 Control Classes (continued) 


Class Description 


EDIT An edit control is a rectangular child window in which the user 
can enter text from the keyboard. The user selects the control, 
and gives it the input focus, by clicking the mouse inside it or 
pressing the TAB key. The user can enter text when the control 
displays a flashing caret. The mouse can be used to move the 
cursor and select characters to be replaced, or to position the 
cursor for inserting characters. The BACKSPACE key can be used 
to delete characters. : 


Edit controls use the fixed-pitch font and display ANSI 
characters. They expand tab characters into as many space 
characters as are required to move the cursor to the next tab 
stop. Tab stops are assumed to be at every eighth character posi- 
tion. 


LISTBOX List-box controls consist of a list of character strings. The con- 
trol is used whenever an application needs to present a list of 
names, such as filenames, that the user can view and select. The 
user can select a string by pointing to the string with the mouse 
and clicking a mouse button. When a string is selected, it is 
highlighted, and a notification message is passed to the parent 
window. A scroll bar can be used with a list-box control to 
scroll lists that are too long or too wide for the control window. 


SCROLLBAR A scroll-bar control is a rectangle that contains a scroll thumb 
and has direction arrows at both ends. The scroll bar sends a 
notification message to its parent whenever the user clicks the 
mouse in the control. The parent is responsible for updating the 
thumb position, if necessary. Scroll-bar controls have the same 
appearance and function as the scroll bars used in ordinary 
windows. But unlike scroll bars, scroll-bar controls can be posi- 
tioned anywhere within a window and used whenever needed to 
provide scrolling input for a window. 


The scroll-bar class also includes size-box controls. A size-box 
control is a small rectangle that the user can expand to change 
the size of the window. 


STATIC Static controls are simple text fields, boxes, and rectangles that 
can be used to label, box, or separate other controls. Static con- 
trols take no input and provide no output. 
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Table 8.3 describes the control styles for each of the control classes: 


Table 8.3. Control Styles 


Style 
BUTTON Class 


BS_PUSHBUTTON 


BS_DEFPUSHBUTTON 


BS_CHECKBOX 


BS_AUTOCHECKBOX 


BS_RADIOBUTTON 


BS_AUTORADIOBUTTON 


BS_LEFTTEXT 


Description 


A small elliptical button containing 
the given text. The control sends a 
message to its parent whenever the 
user clicks the mouse inside the 
rectangle. 


A small elliptical button with a bold 
border. This button represents the 
default user response. Any text is 
displayed within the button. 
Windows sends a message to the 
parent window when the user clicks 
the mouse in this button. 


A small rectangular button that can 
be checked; its border becomes 
bold when the user clicks the mouse 
in it. Any text appears to the right of 
the button. 


Identical to BS_CHECKBOX ex- 
cept that the button automatically 

toggles its state whenever the user 
clicks it. 


A small circular button whose 
border becomes bold when the user 
clicks the mouse in it. In addition, 
to make the border bold, Windows 
sends a message to the button’s 
parent notifying it that a click oc- 
curred. On the next click, Windows 
makes the border normal again and 
sends another message. 


Identical to BS_RADIOBUTTON 
except that when the button is 
checked, the application is notified 
with BN_CLICKED, and all other 
radio buttons in the group are un- 
checked, 


Text appears on the left side of the 
radio button or check-box button. 
Use this style with BS_CHECK- 
BOX, BS_3STATE, or 
BS_RADIOBUTTON styles. 
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Table 8.3 Control Styles (continued) 
Style 


BS_3STATE 


BS_AUTO3STATE 


BS_GROUPBOX 


BS_OWNERDRAW 


COMBOBOX Class 


CBS_SIMPLE 


CBS_ DROPDOWN 


CBS_DROPDOWNLIST 


CBS_OWNERDRAWFIXED 


CBS_OWNERDRAWVARIABLE 


Description 


Identical to BS_CHECKBOX ex- 
cept that a button can be grayed as 
well as checked or unchecked. The 
grayed state is typically used to 
show that a check box has been dis- 
abled. 


Identical to BS_3STATE except that 
the button automatically toggles its 
state when the user clicks it. 


A rectangle into which other but- 
tons are grouped. Any text is 
displayed in the rectangle’s upper- 
left corner. 


An owner-draw button. The parent 
window is notified when the button 
is clicked. Notification includes a re- 
quest to paint, invert, and disable 

the button. 


Displays the list box at all times. 
The current selection in the list box 
is displayed in the edit control. 


Is similar to CBS_SIMPLE, except 
that the list box is not displayed un- 
less the user selects an icon next to 

the selection field. 


Is similar to CBS_DROPDOWN, 
except that the edit control is re- 
placed by a static text item which 
displays the current selection in the 
list box. 


Specifies a fixed-height owner-draw 
combo box. The owner of the list 
box is responsible for drawing its 
contents; the items in the list box 
are all the same height. 


Specifies a variable-height owner- 
draw combo box. The owner of the 
list box is responsible for drawing 
its contents; the items in the list box 
can have different heights. 
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Table 8.3 Control Styles (continued) 
Style 


CBS_AUTOHSCROLL 


CBS_SORT 


CBS_HASSTRINGS 


CBS_OEMCONVERT 


EDIT Class 


ES_LEFT 
ES_CENTER 


ES_RIGHT 


ES_LOWERCASE 


Description 


Scrolls the text in the edit control to 
the right when the user types a 
character at the end of the line. If 
this style is not set, only text which 
fits within the rectangular boundary 
is allowed. 


Sorts strings entered into the list 
box. 


Specifies an owner-draw combo 
box that contains items consisting 
of strings. The combo box main- 
tains the memory and pointers for 
the strings so that the application 
can use the LB_GETTEXT 
message to retrieve the text for a 
particular item. 


Text entered in the combo box edit 
control is converted from the ANSI 
character set to the OEM character 
set and then back to ANSI. This en- 
sures proper character conversion 
when the application calls the Ansi- 
ToOem function to convert an 
ANSI string in the combo box to 
OEM characters. This style is most 
useful for combo boxes that contain 
filenames and applies only to 
combo boxes created with the 
CBS_SIMPLE or CBS_DROP- 
DOWN styles. 


Flush-left text. 


Centered text. This style is valid in 
multiline edit controls only. 


Flush-right text. This style is valid 
in multiline edit controls only. 


Lowercase edit control. An edit con- 
trol with this style converts all 
characters to lowercase as they are 
typed into the edit control. 
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Table 8.3 Control Styles (continued) 
Style 


ES_UPPERCASE 


ES_PASSWORD 


ES_MULTILINE 


Description 


Uppercase edit control. An edit con- 
trol with this style converts all 
characters to uppercase as they are 
typed into the edit control. 


Password edit control. An edit con- 
trol with this style displays all 
characters as an asterisk (*) as they 
are typed into the edit control. An 
application can use the 
EM_SETPASSWORDCHAR 
message to change the character 
that is displayed. 


Multiple-line edit control. (The 
default is single-line.) If the 
ES_AUTOVSCROLL style is 
specified, the edit control shows as 
many lines as possible and scrolls 
vertically when the user presses the 
ENTER key. (This is actually the car- 
riage-return character, which the 
edit control expands to a carriage- 
return/line-feed combination. A line 
feed is not treated the same as a car- 
riage return.) If 
ES_AUTOVSCROLL is not given, 
the edit control shows as many lines 
as possible and beeps if the user 
presses ENTER when no more lines 
can be displayed. 


If the ES_AUTOHSCROLL style is 
specified, the multiple-line edit con- 
trol automatically scrolls 
horizontally when the caret goes 
past the right edge of the control. To 
start a new line, the user must press 
the ENTER key. If ES_AUTO- 
HSCROLL is not given, the control 
automatically wraps words to the 
beginning of the next line when nec- 
essary; a new line is also started if 
the user presses ENTER. The position 
of the wordwrap is determined by 
the window size. If the window size 
changes, the wordwrap position 
changes, and the text is redisplayed. 
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Table 8.3 Control Styles (continued) 


Style Description 


Multiple-line edit controls can have 
scroll bars. An edit control with 
scroll bars processes its own scroll- 
bar messages. Edit controls without 
scroll bars scroll as described 
above, and process any scroll mes- 
sages sent by the parent window. 


ES_AUTOVSCROLL Text is automatically scrolled up 
one page when the user presses the 
ENTER key on the last line. 


ES_AUTOHSCROLL Text is automatically scrolled to the 
right by 10 characters when the user 
types a character at the end of the 
line. When the user presses the 
ENTER key, the control scrolls all 
text back to position 0. 


ES_NOHIDESEL Normally, an edit control hides the 
selection when the control loses the 
input focus, and inverts the selec- 
tion when the control receives the 
input focus. Specifying ES_NO- 
HIDESEL overrides this default 
action. 


ES_OEMCONVERT Text entered in the edit control is 
converted from the ANSI character 
set to the OEM character set and 
then back to ANSI. This ensures 
proper character conversion when 
the application calls the Ansi- 
ToOem function to convert an 
ANSI string in the edit control to 
OEM characters. This style is most 
useful for edit controls that contain 
filenames. 


LISTBOX Class 


LBS_STANDARD Strings in the list box are sorted al- 
phabetically and the parent window 
: receives an input message when- 
ever the user clicks or double-clicks 
a string. The list box contains 
borders on all sides. 
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Table 8.3 Control Styles (continued) 


Style 


LBS_EXTENDEDSEL 


LBS_HASSTRINGS 


LBS_NOTIFY 


LBS_MULTIPLESEL 


LBS_MULTICOLUMN 


LBS_NOINTEGRALHEIGHT 


LBS_SORT 


LBS_NOREDRAW 


LBS_OWNERDRAWFIXED 


LBS_OWNERDRAWVARIABLE 


Description 


The user can select multiple iterns 
using the mouse with the SHIFT 
and/or the CONTROL key or special 
key combinations. 


An owner-draw list box contains 
items consisting of strings. The list 
box maintains the memory and 
pointers for the strings so the appli- 
cation can use the LB_GETTEXT 
message to retrieve the text fora 
particular item. 


The parent receives an input 
message whenever the user clicks 
or double-clicks a string. 


The string selection is toggled each 
time the user clicks or double-clicks 
the string. Any number of strings 
can be selected. 


The list box contains multiple 
columns. The list box can be 
scrolled horizontally. The LB_SET- 
COLUMNWIDTH message sets the 
width of the columns. 


The size of the list box is exactly 
the size specified by the application 
when it created the list box. Nor- 
mally, Windows sizes a list box so 
that the list box does not display 
partial items. 


The strings in the list box are sorted 
alphabetically. 


The list-box display is not updated 
when changes are made. This style 
can be changed at any time by send- 
ing a WM_SETREDRAW message. 


The owner of the list box is re- 
sponsible for drawing its contents; 
the items in the list box are all the 
same height. 


The owner of the list box is re- 
sponsible for drawing its contents; 
the items in the list box are variable 
in height. 


Table 8.3 Control Styles (continued) 


Style 


LBS_USETABSTOPS 


LBS_WANTKEYBOARDINPUT 


SCROLLBAR Class 


SBS_VERT 


SBS_RIGHTALIGN 


SBS_LEFTALIGN 
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Description 


The list box is able to recognize and 
expand tab characters when draw- 
ing its strings. The default tab 
positions are set at every 32 dialog 
units. (A dialog unit is a horizontal 
or vertical distance. One horizontal 
dialog unit is equal to 4 of the cur- 
rent dialog base width unit. The 
dialog base units are computed 
from the height and width of the cur- 
rent system font. The 
GetDialogBaseUnits function re- 
turns the size of the dialog base 
units in pixels.) 


The owner of the list box receives 
WM_VKEYTOITEM or 
WM_CHARTOITEM messages 
whenever the user presses a key 
when the list box has input focus. 
This allows an application to per- 
form special processing on the 
keyboard input. 


Vertical scroll bar. If neither 
SBS_RIGHTALIGN nor SBS_LEF- 
TALIGN is specified, the scroll bar 
has the height, width, and position 
given in the CreateWindow func- 
tion. 


Used with SBS_VERT. The right 
edge of the scroll bar is aligned 
with the right edge of the rectangle 
specified by the x, y, width, and 
height values given in the 
CreateWindow function. The 
scroll bar has the default width for 
system scroll bars. 


Used with SBS_ VERT. The left 
edge of the scroll bar is aligned 
with the left edge of the rectangle 
specified by the x, y, width, and 
height values given in the 
CreateWindow function. The _ 
scroll bar has the default width for 
system scroll bars. 
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Table 8.3 Control Styles (continued) 
Style 


SBS_HORZ 


SBS_TOPALIGN 


SBS_BOTTOMALIGN 


SBS_SIZEBOX 


SBS_SIZEBOXTOPLEFTALIGN 


SBS_SIZEBOXBOTTOMRIGHTALIGN 


Description 


Horizontal scroll bar. If neither 
SBS_BOTTOMALIGN nor 
SBS_TOPALIGN is specified, the 
scroll bar has the height, width, and 
position given in the CreateWin- 
dow function. 


Used with SBS_HORZ. The top 
edge of the scroll bar is aligned 
with the top edge of the rectangle 
specified by the x, y, width, and 
height values given in the 

Create Window function. The 
scroll bar has the default height for 
system scroll bars. 


Used with SBS_HORZ. The bottom 
edge of the scroll bar is aligned 
with the bottom edge of the 
rectangle specified by the x, y, 
width, and height values given in 
the CreateWindow function. The 
scroll bar has the default height for 
system scroll bars. 


Size box. If neither SBS_SIZEBOX- 
BOTTOMRIGHTALIGN nor 
SBS_SIZEBOXTOPLEFTALIGN 
is specified, the size box has the 
height, width, and position given in 
the CreateWindow function. 


Used with SBS_SIZEBOX. The top- 
left corner of the size box is aligned 
with the top-left corner of the 
rectangle specified by the x, y, 
width, and height values given in 
the CreateWindow function. The 
size box has the default size for sys- 
tem size boxes. 


Used with SBS_SIZEBOX. The bot- 
tom-right corer of the size box is 
aligned with the bottom-right corner 
of the rectangle specified by the x, 

y, width, and height values given in 
the CreateWindow function. The 
size box has the default size for sys- 
tem size boxes. 


Resource Script Statements 8-45 


Table 8.3. Control Styles (continued) 


Style Description 
STATIC Class 
SS_LEFT A simple rectangle displaying the 


given text flush left in the rectangle. 
The text is formatted before it is dis- 
played. Words that would extend 
past the end of a line are automati- 
cally wrapped to the beginning of 
the next line. 


SS_CENTER A simple rectangle displaying the 
given text centered in the rectangle. 
The text is formatted before it is dis- 
played. Words that would extend 
past the end of a line are automati- 
cally wrapped to the beginning of 
the next line. 


SS_RIGHT A simple rectangle displaying the 
given text flush right in the 
rectangle. The text is formatted 
before it is displayed. Words that 
would extend past the end of a line 
are automatically wrapped to the 
beginning of the next line. 


SS_LEFTNOWORDWRAP A simple rectangle displaying the 
given text flush left in the rectangle. 
Tabs are expanded, but words are 
not wrapped. Text that extends past 
the end of a line is clipped. 


SS_SIMPLE Designates a simple rectangle and 
displays a single line of text flush- 
left in the rectangle. The line of text 
cannot be shortened or altered in 
any way. (The control’s parent 
window or dialog box must not 
process the WM_CTLCOLOR 
message.) 
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Table 8.3 Control Styles (continued) 


Style 


SS_NOPREFIX 


Description 


Unless this style is specified, 


SS_ICON 


SS_BLACKRECT 
SS_GRAYRECT 
SS_WHITERECT 


SS_BLACKFRAME 


windows will interpret any “&”’ 
characters in the control’s text to be 
accelerator prefix characters. In this 
case, the “‘&’’ is removed and the 
next character in the string is under- 
lined. If a static control is to contain 
text where this feature is not 
wanted, SS_NOPREFIX may be 
added. This static-control style may 
be included with any of the defined 
static controls. 


You can combine SS_NOPREFIX 
with other styles by using the 
bitwise OR operator. This is most 
often used when filenames or other 
strings that may contain an “&” 
need to be displayed in a static con- 
trol in a dialog box. 


An icon displayed in the dialog box. 
The given text is the name of an 
icon (not a filename) defined else- 
where in the resource file. For the 
ICON statement, the width and 
height parameters in the 

Create Window function are ig- 
nored; the icon automatically sizes 
itself. 


A rectangle filled with the color 
used to draw window frames. This 
color is black in the default 
Windows color scheme. 


A rectangle filled with the color 
used to fill the screen background. 
This color is gray in the default 
Windows color scheme. 


A rectangle filled with the color 
used to fill window backgrounds. 
This color is white in the default 
Windows color scheme. 


Box with a frame drawn with the 
same color as window frames. This 
color is black in the default 
Windows color scheme. 


Resource Script Statements 8-47 


Table 8.3. Control Styles (continued) 


Style Description 


SS_GRAYFRAME Box with a frame drawn with the 
same color as the screen back- 
ground (desktop). This color is gray 
in the default Windows color 
scheme. 

SS_WHITEFRAME Box with a frame drawn with the 
same color as window backgrounds. 
This color is white in the default 
Windows color scheme. 


SS_USERITEM User-defined item. 


8.8 Directives 


The resource directives are special statements that define actions to be performed 
on the script file before it is compiled. The directives can assign values to names, 
include the contents of files, and control compilation of the script file. 


The resource directives are identical to the directives used in the C programming 
language. They are fully defined in the Microsoft C Language Reference. 


8.8.1 #include Statement 
Syntax 


#include filename 


This directive copies the contents of the file specified by filename into your 
resource script before the Resource Compiler processes the script. It replaces the 
rcinclude directive of versions prior to Windows 3.0. 


The filename field is an ASCII string that specifies the DOS filename of the file 
to be included, using the same syntax as the C-language preprocessor #include 
directive. A forward slash (/) can be used instead of a backslash (for example, 
“root/sub”). If the filename has the .H or .C extension, only the preprocessor 
directives in the file are processed. Otherwise, this directive processes the entire 
contents of the file. 
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The following example demonstrates the correct usage of the #include statement: 


#Hinclude "“WINDOWS.H" 


PenSelect MENU 
BEGIN 

Menuitem "&Black pen", BLACK_PEN 
END 


8.8.2 #define Statement 
Syntax | 


#define name value 


This directive assigns the given value to name. All subsequent occurrences of 
name are replaced by value. 


The value field takes any integer value, character string, or line of text. 


The following example demonstrates the correct usage of the #define statement: 


i##define nonzero 1 

dtdefine USERCLASS  "MyControlClass” 
8.8.3 #undef Statement 

Syntax 

#undef name 


This directive removes the current definition of name. All subsequent occur- 
rences of name are processed without replacement. 


The following example demonstrates the correct usage of the #undef statement: 


dtundef nonzero 
dtundef ; USERCLASS 


8.8.4 #ifdef Statement 


Syntax 
#ifdef name 


This directive carries out conditional compilation of the resource file by checking 
the specified name. If name has been defined using a #define directive, #ifdef 
directs the Resource Compiler to continue with the statement immediately after 
#ifdef. If name has not been defined, #ifdef directs the compiler to skip all state- 
ments up to the next #endif directive. 
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Thr following example demonstrates the correct usage of the #ifdef statement: 


#ifdef Debug 
errbox BITMAP errbox.bmp 
fendi f 


8.8.5 #ifndef Statement 
Syntax 


#ifndef name 


This directive carries out conditional compilation of the resource file by checking 
the specified name. If name has not been defined or if its definition has been re- 
moved using the #undef directive, #ifndef directs the Resource Compiler to con- 
tinue processing statements up to the next #endif, #else, or #elif directive, and 
then to skip to the statement after #endif. If name is defined, #ifndef directs the 
compiler to skip to the next #endif, #else, or #elif directive. 


The following example demonstrates the correct usage of the #ifndef statement: 


#ifndef Optimize 
errbox BITMAP errbox.bmp 
#tendif 


8.8.6 #if Statement 
Syntax 


' #if constant-expression 


This directive carries out conditional compilation of the resource file by checking 
the specified constant-expression. If constant-expression is nonzero, #if directs 
the Resource Compiler to continue processing statements up to the next #endif, 
#else, or #elif directive, then skip to the statement after #endif. If constant-ex- 
pression is zero, #if directs the compiler to skip to the next #endif, #else, or #elif 
directive. 


The constant-expression field specifies a defined name, an integer constant, or an 
expression consisting of names, integers, and arithmetical and relational opera- 
tors. 


The following example demonstrates the correct usage of the #if statement: 


#if Version<3 
errbox BITMAP errbox.bmp 
fendi f 
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8.8.7 #elif Statement 
| Syntax 


#elif constant-expression 


This directive marks an optional clause of a conditional compilation block de- 
fined by an #ifdef, #ifndef, or #if directive. The #elif directive carries out condi- 
tional compilation of the resource file by checking the specified constant- 
expression. If constant-expression is nonzero, #elif directs the Resource Com- 
piler to continue processing statements up to the next #endif, #else, or #elif direc- 
tive, then skip to the statement after #endif. If constant-expression is zero, #elif 
directs the compiler to skip to the next #endif, #else, or #elif directive. Any num- 
ber of #elif directives can be used in a conditional block. 


The constant-expression field specifies a defined name, an integer constant, or an 
expression consisting of names, integers, and arithmetical and relational opera- 
tors. 


The following demonstrates the correct usage of the #elif statement: 


#if Version<3 

errbox BITMAP errbox.bmp 
#felif Version<7 

errbox BITMAP userbox. bmp 
#endif 


8.8.8 #else Statement 
Syntax 


#else 


This directive marks an optional clause of a conditional compilation block de- 
fined by an #ifdef, #ifndef, or #if directive. The #else directive must be the last 
directive before #endif. 


The following example demonstrates the correct usage of the #else statement: 


fHifdef Debug 

errbox BITMAP errbox.bmp 
ffelse 

errbox BITMAP userbox. bmp 
dtendif 
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8.8.9 #endif Statement 


8.9 Summary 


Syntax 
#Hendif 


This directive marks the end of a conditional compilation block defined by an #if 
or #ifdef directive. One #if or #endif is required for each #ifdef directive. 


The resource script statements define resources that the Resource Compiler adds 
to an application’s executable file. The application can then load these resources 
as they are needed at run time. For more information on topics related to the 
Resource Compiler, see the following: 


Topic Reference 

General information on Guide to Programming: Chapter 1, “An 

Windows programming Overview of the Windows Environment” 

Menus Guide to Programming: Chapter 7, ““Menus” 

Controls and dialog boxes Guide to Programming: Chapter 8, 
“Controls,” and Chapter 9, “Dialog Boxes” 

Using the Resource Tools: Chapter 3, “Compiling Resources: 

Compiler The Resource Compiler” 

Designing dialog boxes Tools: Chapter 5, “Designing Dialog Boxes: 


The Dialog Editor” 


Chapter || Fife Formats 


9 


This chapter describes the file formats used to create, execute, and supply data to 
Microsoft Windows applications. These files include the following: 


= Bitmap files 

= Icon resource files 

= Cursor resource files 
= Clipboard files 


= Metafiles 


9.1 Bitmap File Formats 


Windows version 3.0 bitmap files store a bitmap in a device-independent format 
which allows Windows to display the bitmap on any device. In this case, the term 
“device independent” means that the bitmap specifies pixel color in a form inde- 
pendent of the method used by any particular device to represent color. The as- 
sumed file extension of a Windows device-independent bitmap file is .BMP. 


Each bitmap file contains a BITMAPFILEHEADER data structure immedi- 
ately followed by a single, device-independent bitmap (DIB) consisting of a 
BITMAPINFO data structure and an array of bytes that defines the bitmap bits. 


Windows version 3.0 also reads bitmap files in the format read by Microsoft 
OS/2 Presentation Manager version 1.2. These files consist of a BITMAPFILE- 
HEADER data structure immediately followed by a BITMAPCOREINFO data 
structure. Following this data structure is an array of bytes that defines the bit- 
map bits. 


See Chapter 7, “Data Types and Structures,” for information on the BITMAP- 
FILEHEADER, BITMAPCOREINFO and BITMAPINEFO data structures. 
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9.2 lcon Resource File Format 


An icon resource file (with the .I[CO file extension) can be device independent 
both for color and resolution. 


Icon resource files can contain multiple device-independent bitmaps defining the 
icon image, one for each targeted display-device resolution. Windows detects the 
resolution of the current display and matches it against the x and y pixel-size 
values specified for each version of the image. If Windows determines that there 
is an exact match between an icon image and the current device, then it uses the 
matching image; otherwise, it selects the closest match and stretches the image to 
the proper size. 


If an icon resource file contains more than one image for a particular resolution, 
Windows uses the icon image that most closely matches the color capabilities of 
the current display device. If no image exists which exactly matches the device 
capabilities, Windows selects the image which has the greatest number of colors 
without exceeding the number of display-device colors. If all images exceed the 
color capabilities of the current display device, then Windows uses the icon 
image with the least number of colors. 


The icon resource file contains a header structure at the beginning of the file 
which identifies the type and number of icon images contained in the file. The 
following shows the format of this header: 


Field Type/Description 

icoReserved WORD Is reserved and must be set to 0. 

icoResourceType WORD Specifies the type of resource contained 
in the file. For an icon resource, this field must be 1. 

icoResourceCount WORD _ Specifies the number of images contained 
in the file. 


The resource directory follows this header. The resource directory consists of one 
or more arrays of resource descriptors. The icoResorceCount specifies the num- 
ber of arrays. The following list shows the format of the array: 


Field Type/Description 

Width BYTE = Specifies the width in pixels of this form 
of the icon image. Acceptable values are 16, 32, or 
64. 

Height BYTE Specifies the height in pixels of this form 


of the icon image. Acceptable values are 16, 32, or 
64. 
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Field Type/Description 

ColorCount BYTE Specifies the number of colors in this form 
of the icon image. Acceptable values are 2, 8, or 16. 

Reserved BYTE Reserved for future use. 

Reserved WORD Reserved for future use. 

Reserved WORD Reserved for future use. 

icoDIBSize DWORD Specifies in bytes the size of the pixel 
array for this form of the icon image. 

icoD]BOffset DWORD _Specifies the offset in bytes from the 


beginning of the file to the device-independent bit- 
map for this form. 


Icons can be in color. To achieve transparency, the DIB for each icon will consist 
of two parts: 


1. The first part is a color bitmap which supplies the XOR mask for the icon. 


2. The second part is a monochrome bitmap which provides the AND mask that 
defines the transparent portion of the icon. 


The monochrome bitmap does not contain a DIB header, but instead immediately 
follows the color bitmap. It must have the same pixel height as the color bitmap. 


9.3 Cursor Resource File Format 


Like icon resource files, cursor resource files (with the .CUR file extension) may 
contain multiple images to match targeted display-device resolutions. In the case 
of cursors, Windows determines the best match for a particular display-device 
driver by examining the width and height of the cursor images. 


The cursor resource file contains a header structure at the beginning of the file 
which identifies the type and number of resources in the file. The following 
shows the format of this header: 


Field Type/Description 
curReserved WORD Is reserved and must be set to 0. 
curResourceType WORD _Specifies the type of resource contained 


in the file. For a cursor resource, this field must be 2. 


curResourceCount WORD _Specifies the number of resources con- 
tained in the file. 
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The resource directory follows this header. The resource directory consists of one 
or more arrays of resource descriptors. The curResorceCount specifies the num- 
ber of arrays. The following shows the format of the array: 


Field Type/Description 

cur Width BYTE Specifies the width in pixels of this form 
of the cursor image. 

curHeight BYTE Specifies the height in pixels of this form 
of the cursor image. 

ColorCount BYTE Specifies the number of colors in this form 

. of the icon image. Acceptable values are 2, 8, or 16. 

Reserved BYTE Is reserved and must be set to 0. 

cur XHotspot WORD Specifies in pixels the horizontal position 
of the hotspot. 

cur Y Hotspot WORD _ Specifies in pixels the vertical position of 
the hotspot. 

curDIBSize DWORD Specifies in bytes the size of the pixel 
array for this form of the cursor image. 

curDIBOffset DWORD Specifies in bytes the offset to the 


device-independent bitmap for this form. The offset 
is from the beginning of the file. 


Cursors are monochrome. The bitmap for a cursor consists of two parts; the first 
half is the XOR mask specifying the visible image, and the second half is the 
AND mask specifying the transparent portion of the cursor image. The two parts 
must be of equal width and height. By combining the values in corresponding 
mask bits, Windows determines whether a pixel is black, white, inverted, or trans- 
parent. 


Table 9.1 shows what values are necessary to produce the corresponding colors, 
inversions, or transparencies: 


Table9.1 = Bit Mask Results 


Bit Value Bit Value Bit Value Bit Value 


AND mask 0 0 | 1 
XOR mask 0 1 0 1 
Resultant Pixel Black White Transparent Inverted 
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Figure 9.1 shows two bitmaps that represent the AND mask and the XOR mask 
for a cursor. The bit settings in the two bitmaps create a black, cross-shaped 


Cursor: 


Resultant 
Cursor 


Figure 9.1 Settings and Resultant Cursor 


9.4 Clipboard File Format 


The Windows clipboard saves and reads clipboard data in files with the .CLP ex- 
tension. A clipboard-data file contains a value that identifies it as a clipboard- 
data file, one or more data structures defining the format, size, and porauon of the 
clipboard data, and one or more blocks of the actual data. 


The clipboard-data file begins with a header consisting o two fields. The follow- 
ing describes these fields: 


Field Type/Description 


FileIdentifier WORD Identifies the file as a clipboard-data file. 
This field must be set to CLP_ID. 


FormatCount WORD _ Specifies the number of clipboard for- 
mats contained in the file. 


This header is followed by one or more data structures, each of which identifies 
the format, size, and offset of a block of clipboard data. The following shows the 
fields of this data structure: 


Field Type/Description 


FormatID WORD Specifies the clipboard-format ID of the 
clipboard data. See the description of the SetClip- 
boardData function in Chapter 4, “Functions 
Directory,” in Reference, Volume 1, for information 
on clipboard formats. 


LenData DWORD Specifies in bytes the length of the clip- 
board data. 
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Field Type/Description 

OffData DWORD Specifies in bytes the offset of the clip- 
board-data block. The offset is from the beginning 
of the file. 

Name Is a 79-character array that specifies the format 


name for a private clipboard format. 


The first block of clipboard data follows the last of these structures. For bitmaps 
and metafiles, the bits follow immediately after the bitmap header and the 
METAFILEPICT data structures. 


9.5 Metafile Format 


A metafile consists of a collection of graphics device interface (GDI) function 
calls that create specific images on a device. Metafiles provide convenient 
storage for images that appear repeatedly in applications, and also allow you to 
use the clipboard to cut and paste images from one application to another. 


Metafiles store images as a series of GDI function calls. After storing the func- 
tion calls, applications play a metafile to generate an image on a device. 


When an object is created during playback, GDI adds the handle of the object to 
the first available entry in the metafile handle table. GDI clears the table entry 
corresponding to the object when it is deleted during playback, allowing the table 
entry to be reused when another object is created. 


NOTE Functions described in this section are discussed in greater detail in Chapter 4, 
“Functions Directory,” in Reference, Volume 1. 


The metafile itself consists of two parts: a header and a list of records. The 
header contains a description of the size (in words) of the metafile and the num- 
ber of drawing objects it uses. The list of records contains the GDI functions. The 
drawing objects can be pens, brushes, or bitmaps. 


9.5.1 Metafile Header 


The following structured list shows the format of the metafile header: 


struct { 

WORD = mtType; 

‘WORD mtHeaderSize; 
WORD mtVersion; 
DWORD mtSize; 

WORD mtNoObjects; 
DWORD mtMaxRecord; 


File Formats 9-7 


WORD mtNoParameters; 
} 


The metafile header contains the following fields: 


Field Description 


mtType Specifies whether the metafile is in memory or re- 
corded in a disk file. It is one of these two values: 


Value Meaning 

l Metafile is in memory 

Zz Metafile is in a disk file 
mtHeaderSize Specifies the size in words of the metafile header. 
mt Version Specifies the Windows version number. The ver- 

sion number for Windows version 3.0 is 0x300. 
mtSize Specifies the size in words of the file. 
mtNoObjects : Specifies the maximum number of objects that 


exist in the metafile at the same time. 


mtMaxRecord Specifies the size in words of the largest record in 
the metafile. 


mtNoParameters Is not used. 


9.5.2 Metafile Records 


A series of records follows the metafile header. Metafile records describe GDI 
functions. GDI stores most of the GDI functions that an application can use to 
create metafiles in similar, typical records. “Typical Metafile Record,” later in 
this section, shows the format of the typical metafile record. Table 9.2, “GDI 
Functions and Values,” lists the functions which GDI records in typical records, 
along with their respective function numbers. 


The remainder of the functions contain more complex structures in their records. 
‘“Function-Specific Records,” later in this section, describes the records for these 
functions. 


In some cases, there are two versions of a metafile record. One version represents 
the record created by versions of Windows prior to version 3.0, while the second 
version represents the record created by Windows versions 3.0 and later. 
Windows 3.0 plays all metafile versions, but stores only 3.0 versions. Windows 
versions prior to 3.0 will not play metafiles recorded by Windows 3.0. 
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Table 9.2 GDI Functions and Values 


Function Value 
Arc 0x0817 
Chord 0x0830 
Ellipse 0x0418 
ExcludeClipRect 0x0415 
FloodFill 0x0419 
IntersectClipRect 0x0416 
LineTo 0x0213 
MoveTo 0x0214 
OffsetClipRgn 0x0220 
Offset ViewportOrg 0x0211 
Offset WindowOrg 0x020F 
PatBlt . 0x061D 
Pie Ox081A 
RealizePalette (3.0 and later) | 0x0035 
Rectangle 0x041B 
ResizePalette (3.0 and later) 0x0139 
RestoreDC 0x0127 
RoundRect 0x061C 
SaveDC OxO01E 
ScaleViewportExt 0x0412 
ScaleWindowExt 0x0400 
SetBkColor 0x0201 
SetBkMode 0x0102 
SetMapMode 0x0103 
SetMapperFlags 0x0231 
SetPixel 0x041F 
SetPolyFillMode 0x0106 
SetROP2 | 0x0104 
SetStretchBItMode _ 0x0107 
SetTextAlign 0x012E 
SetTextCharExtra 0x0108 
SetTextColor 0x0209 
SetTextJustification 0x020A 


Set ViewportExt 0x020E 
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Table 9.2 GDI Functions and Values (continued) 


Function Value 

SetViewportOrg 0x020D 
SetWindowExt 0x020C 
SetWindowOrg 0x020B 


Typical Metafile Record 


The following structured list shows the format of a typical metafile record: 


Structt 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParm{]; 

} 


A typical metafile record contains the following fields: 


Field Description 

rdSize Specifies the size in words of the record. 

rdFunction Specifies the function number. 

rdParn] | ' Ts an array of words containing the function parameters, 
in the reverse order in which they are passed to the func- 
tion. 


Function-Specific Records 


Some metafile records contain data structures in the parameter field. This section 
contains definitions for these records. 


AnimatePalette Record 


The AnimatePalette record has the following format: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParm([]; 

} 


This record contains the following fields: 
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Field Description 

rdSize Specifies the record size in words. 

rdFunction Specifies the function number 0x0436. 

rdParn ] Contains the following elements: 
Element Description 
start First entry to be animated. 
numentries Number of entries to be animated. 
entries PALETTEENTRY blocks. 


BitBlt Record (Prior to 3.0) 


The BitBlIt record stored by Windows versions prior to 3.0 contains a device-de- 
pendent bitmap which may not be suitable for playback on all devices. The fol- 
lowing is the format of this record: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParm(]; 

} 


This record contains the following fields: 


Field Description 
rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x0922 . 
rdParn{ |] Contains the following elements: 
Element Description 
raster op High word of the raster opera- 
tion. 
SY The y-coordinate of the source 
. origin. 
SX The x-coordinate of the source 
origin. 


DYE Destination y-extent. 
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Field Description 

Element Description 

DXE Destination x-extent. 

DY The y-coordinate of destina- 
tion origin. 

DX The x-coordinate of destina- 
tion origin. 

bmWidth Width of bitmap (in pixels) 

bmHeight Height of bitmap (in raster 
lines) 

bmWidthBytes Number of bytes in each raster 
line. 

bmPlanes Number of color planes in the 
bitmap. 

bmBitsPixel Number of adjacent color bits. 

bits Actual device-dependent bit- 
map bits. 


BitBit Record 


The BitBIt record stored by Windows versions 3.0 and later contains a device-in- 
dependent bitmap suitable for playback on any device. The following is the for- 
mat of this record: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParm[]; 

} 


This record contains the following fields: 


Field Description 
’ rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x0940. 


rdParn{ |] Contains the following elements: 
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Field 


Description 


‘Element 


raster op 
SY 
SX 


DYE 
DXE 
DY 


DX 


BitmapInfo 
bits — 


CreateBrushindirect Record 
The CreateBrushIndirect record has the following format: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
LOGBRUSH rdParn; 


} 


This record contains the following fields: 


Field 


rdSize 


rdFunction 


rdParm 


Description 


Description 


High word of the raster opera- 
tion. 


The y-coordinate of the source 
origin. 
The x-coordinate of the source 
origin. 
The y-extent of the destination. 


The x-extent of the destination. 


The y-coordinate of destina- 
tion origin. 


The x-coordinate of destina- 
tion origin. 
BITMAPINFO data structure. 


Actual device-independent bit- 
map bits. 


Specifies the record size in words. 


Specifies the function number 0x02FC. 


Specifies the logical brush. 
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CreateFontindirect Record 
The CreateFontIndirect record has the following format: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
LOGFONT rdParm; 
} 


This record contains the following fields: 


Field Description 

rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x02FB. 
rdParm Specifies the logical font. 


CreatePalette Record 


The CreatePalette record has the following format: 


struct { 

DWORD rdSize; 

WORD rdFunction; 
LOGPALETTE rdParm; 
} 


This record contains the following fields: 


Field Description 

rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x00F7. 
rdParm Specifies the logical palette. 


CreatePatternBrush Record (Prior to 3.0) 


The CreatePatternBrush record stored by Windows versions prior to 3.0 con- 
tains a device-dependent bitmap which may not be suitable for playback on all 
devices. The following is the format of this record: 


Struct { 

DWORD rdSize; 
WORD rdFunction; | 
WORD rdParm[]; 

} 
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This record contains the following fields: 


Field Description 

rdSize Specifies the record size in words. 

rdFunction Specifies the function number 0x01F9. 

rdParn ] Contains the following elements: 
Element Description 
bmWidth Bitmap width. 
bmHeight Bitmap height. 
bmWidthBytes Bytes per raster line. 
bmPlanes Number of color planes. 
bmBitsPixel Number of adjacent color bits 

that define a pixel. 

bmBits Pointer to bit values. 
bits Actual bits of pattern. 


CreatePatternBrush Record 


The CreatePatternBrush record stored by Windows versions 3.0 and later con- 
tains a device-independent bitmap suitable for playback on all devices. The fol- 
lowing is the format of this record: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParm[]; 

} 


This record contains the following fields: 


Field Description 
rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x0142. 


rdParn } ‘Contains the following elements: 
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Field Description 


Element Description 


type Bitmap type. This field may 
be either of these two values: 


= BS_PATTERN—Brush is 
defined by a device-de- 
pendent bitmap through a 
call to the CreatePat- 
ternBrush function. 


a BS_DIBPATTERN— 
Brush is defined by a 
device-independent bitmap 
through a call to the 
CreateDIBPatternBrush 
function. , 


Usage Specifies whether the bmi- 
Colors[ ] field of the 
BITMAPINFO data structure 
contains explicit RGB values 
or indexes into the currently 
realized logical palette. This 
field must be one of the fol- 
lowing values: 


=» DIB_RGB_COLORS— 
The color table contains 
literal RGB values. 


m DIB_PAL_COLORS— 
The color table consists of 
an array of indexes into the 
currently realized logical 
palette. 


BitmapInfo BITMAPINFO data structure. 


bits Actual device-independent bit- 
map bits. 
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CreatePenindirect Record 
The CreatePenIndirect record has the following format: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
LOGPEN rdParm; 

} 


This record contains the following fields: 


Field Description 

rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x02FA. 
rdParm Specifies the logical pen. 

Create Region Record 


The Create Region record has the following format: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParm(J; 

} 


This record contains the following fields: 


Field Description 

rdSize . Specifies the record size in words. 
rdFunction Specifies the function number Ox06FF. 
rdParn] ] Specifies the region to be created. 


Delete Object 


The DeleteObject record has the following format: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParm; 

} 


This record contains the following fields: 
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Field Description 

rdSize Specifies the record size in words. 

rdFunction Specifies the function number 0x01FO0. 

rdParm Specifies the handle-table index of the object to be 
deleted. 

DrawText Record 


The DrawText record has the following format: 


struct{ 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParm[]; 

} 


This record contains the following fields: 


Field Description 
rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x062F. 
rdParn|[ |] Contains the following elements: 
Element Description 
format Method of formatting. 
count Number of bytes in the string. 
rectangle Rectangular structure defining 
area where text is to be defined 
string Byte array containing the 
string. The array is 
((count + 1) >> 1) words long. 
Escape Record 


The Escape record has the following format: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParm[]; 

} 
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This record contains the following fields: 


Field Description 
rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x0626. 
rdParn[ |] Contains the following elements: 
Element Description 
escape number Number identifying in- 
dividual escape. 
count Number of bytes of 
information. . 
input data Variable length field. 
The field is 
((count+1)/ >> 1) 
words long. 
ExtTextOut Record 
The ExtTextOut record has the following format: 
struct { 
DWORD rdSize; 
WORD rdFunction; 
WORD rdParm[]; 
} 
This record contains the following fields: 
Field Description 
rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x0A32. 
rdParn| ] Contains the following elements: 
Element Description 
y Logical y-value of string’s 
starting point. 
X Logical x-value of string’s 


starting point. 
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Field 


Polygon Record 


Description 

Element Description 

count Length of the string. 

options Rectangle type. 

rectangle RECT structure defining the 
ExtTextOut rectangle if op- 
tions element is nonzero; 
nonexistent if options element 
equals zero. 

string Byte array containing the 
string. The array is 
((count + 1) >> 1) words long. 

dxarray Optional word array of inter- 


character distances. 


The Polygon record has the following format: 


struct { 
DWORD rdSize; 


WORD rdFunction; 


WORD rdParm[]; 
} 


This record contains the following fields: 


Field 
rdSize 
rdFunction 


rdParn{ ] | 


Description 
Specifies the record size in words. 
Specifies the function number 0x0324. 


Contains the following elements: 


Element Description 


count Number of points. 


list of points List of individual points. 
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PolyPolygon Record 


The PolyPolygon record has the following format: 
struct { 
DWORD rdSize; 


WORD rdFunction; 
WORD rdParm[]; 


This record contains the following fields: 


Field Description 
rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x0538. 
rdParn] | Contains the following elements: 
Element Description 
count Total number of points. 
list of polygon List of number of points for 
counts each polygon. 
list of points List of individual points. 
Polyline Record 


The Polyline record has the following format: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParm[]; 

} 


This record contains the following fields: 


Field Description 
rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x0325. 


rdParn |] Contains the following elements: 
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Field Description 

Element Description 

count Number of points. 

list of points List of individual points. 
SelectClipRegion 


The SelectClipRegion record has the following format: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParm; 

} 


This record contains the following fields: 


Field Description 

rdSize Specifies the record size in words. 

rdFunction Specifies the function number 0x012C. 

rdParm Specifies the handle-table index of the region 
being selected. 

SelectObject 


The SelectObject record has the following format: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParm; 

} 


This record contains the following fields: 


Field Description 

rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x012D. 
rdParm Specifies the handle-table index of the object 


being selected. 
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SelectPalette Record 


The SelectPalette record has the following format: 


struct { . 
DWORD rdSize; 
WORD rdFunction; 
WORD rdParm; 


This record contains the following fields: 


Field Description 
rdSize Specifies the record size in words. 

_ rdFunction . Specifies the function number 0x0234. 
rdParm Specifies the handle-table index of the logical 


palette being selected. 


SetD|BitsToDevice Record 


The SetDIBitsToDevice record has the following format: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParm[]; 

} 


This record contains the following fields: 


Field Description 
rdSize Specifies the record size in words. — 
rdFunction Specifies the function number 0x0D33. 
rdParn] |] Contains the following elements: 
Element Description 
wUsage | Flag indicating whether the 


bitmap color table contains 
RGB values or indexes into 
the currently realized logical 
palette. 


File Formats 9-23 


Field Description 

Element Description 

numscans — Number of scan lines in the 
bitmap. 

startscan First scan line in the bitmap. 

srcY The y-coordinate of the origin 
of the source in the bitmap. 

srcX The x-coordinate of the origin 
of the source in the bitmap. 

extY Height of the source in the bit- 
map. 

extX Width of the source in the bit- 
map. 

destY The y-coordinate of the origin 
of the destination rectangle. 

destX The x-coordinate of the origin 
of the destination rectangle. 

BitmapInfo BITMAPINFO data structure. 

bits Actual device-independent bit- 
map bits. 


SetPaletteEntries Record 


The SetPaletteEntries record has the following format: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParm[]; 

} 


This record contains the following fields: 


Field Description 
rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x0037. 


rdParn{ ] Contains the following elements: 
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Field Description 
Element Description 
start First entry to be set in the 
palette. 
numentries Number of entries to be set in 
_ the palette. 


entries PALETTEENTRY blocks. 


StretchBit Record (Prior to 3.0) 


The StretchBIt record stored by Windows versions prior to 3.0 contains a device- 
dependent bitmap which may not be suitable for piace on all devices. The fol- 
lowing is the format of this record: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParm[]; 

} 


This record contains the following fields: 


Field Description 
rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x0B23. 
rdParn{ ] Contains the following elements: 
Element Description 
raster op Low word of the raster opera- 
tion. 
raster op. High word of the raster opera- 
tion. 
SYE The y-extent of the source. 
SXE The x-extent of the source. 
SY The y-coordinate of the source 


origin. 
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Field 


Description 


Element 


SX 


DYE 
DXE 
DY 


DX 


bmWidth 
bmHeight 


bmWidthBytes 


bmPlanes 


bmBitsPixel 


bits 


StretchBIt Record 


The StretchBIt record stored by Windows versions 3.0 and later contains a 
device-independent bitmap suitable for playback on all devices. The following is 
the format of this record: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParm[]; 


} 


Description 


The x-coordinate of the source 
origin. 
The y-extent of the destination. 


The x-extent of the destination. 


The y-coordinate of destina- 
tion origin. 


The x-coordinate of destina- 
tion origin. 


Width of the bitmap in pixels. 


Height of the bitmap in raster 
lines. 


Number of bytes in each raster 
line. 


Number of color planes in the 
bitmap. 


Number of adjacent color bits. 


Actual bitmap bits. 
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This record contains the following fields: 


Field Description 
rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x0B41. 
rdParn[ ] Contains the following elements: 
Element Description 
raster op Low word of the raster opera- 
tion. 
raster op High word of the raster opera- 
tion. 
SYE The y-extent of the source. 
SXE The x-extent of the source. 
SY The y-coordinate of the source 
origin. 
SX The x-coordinate of the source 
origin. 
DYE The y-extent of the destination. 
DXE | The x-extent of the destination. 
DY _ The y-coordinate of destina- 
tion origin. 
DX The x-coordinate of destina- 
tion origin. 
BitmapInfo BITMAPINFO data structure. 
bits Actual device-independent bit- 
map bits. 


StretchDIBits Record 
The StretchDIBits record has the following format: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParm[J; 

} 
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This record contains the following fields: 


Field Description 
rdSize Specifies the record size in words. 
rdFunction Specifies the function number 0x0F43. 
rdParn{ J Contains the following elements: 
Element Description 
dwRop Raster operation to be per- 
formed. 
wUsage Flag indicating whether the 
bitmap color table contains 
RGB values or indexes into 
the currently realized logical 
palette. 
srcYExt Height of the source in the bit- 
map. 
srcXExt Width of the source in the bit- 
map. 
srcY The y-coordinate of the origin 
of the source in the bitmap. 
srcX The x-coordinate of the origin 
of the source in the bitmap. 
dstYExt Height of the destination 
rectangle. 
dstXExt Width of the destination 
rectangle. 
dstY The y-coordinate of the origin 
of the destination rectangle. 
dstX The x-coordinate of the origin 
of the destination rectangle. 
BitmapInfo BITMAPINFO data structure. 
bits Actual device-independent bit- 


map bits. 
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TextOut Record 


The TextOut record has the following format: 


struct { 

DWORD rdSize; 
WORD rdFunction; 
WORD rdParm[]; 

} 


This record contains the following fields: 


Field Description 

rdSize Specifies the record size in words. 

rdFunction Specifies the function number 0x0521. 

rdParn ] Contains the following elements: 
Element Description 
count The string’s length. 
string The actual string. 
y-value Logical y-coordinate of 

string’s starting point. 

x-value Logical x-coordinate of 


string’s starting point. 


9.5.3 Sample Metafile Program Output | 


This section shows the metafile created by a sample program. 


The following sample program creates a small metafile in which a purple 
rectangle with a green border is drawn, and the words “Hello People” are written 
in the rectangle. 


MakeAMetaFile(hDC) 

HDC hDC; 

{ 

HPEN hMetaGreenPen; 
HBRUSH hMetaVioletBrush; 
HDC hDCMeta; 


HANDLE hMeta; 


/* create the metafile with output going to the disk 
* 
hDCMeta = CreateMetaFile( (LPSTR) “sample.met"); 
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hMetaGreenPen = CreatePen(@, @, (DWORD) OxQQQBFFQQ); 
SelectObject(hDCMeta, hMetaGreenPen) ; 


hMetaVioletBrush = CreateSolidBrush( (DWORD) 
OxOQFFOAFF); 

SelectObject(hDCMeta, hMetaVioletBrush) ; 
Rectangle(hDCMeta, 8, 0, 150, 70); 

TextOut(hDCMeta, 10, 10, (LPSTR) "Hello People", 12); 


/* we are done with the metafile */ 
hMeta = CloseMetaFile(hDCMeta); 


/* play the metafile that we just created */ 
PlayMetaFile(hDC, hMeta); 
} 


The resulting binary file SAMPLE.MET looks like this: 


Q081 mtType... disk metafile 
0089 mtSize... 

0188 mtVersion 

Q280 8036 mtSize 

QBB2 mtNoObjects 

Q0BB BVBC mtMaxRecord 

QOLO mtNoParameters 


GOB BBB8 rdSize 
QO2FA rdFunction (CreatePen function call) 
GQO0 YB BOGB BBGB FFOB rdParm (LOGPEN structure defining pen) 


GB00 B04 rdSize 
@12D rdFunction (SelectObject) 
QVVO rdParm (index to object #@... the above pen) 


QQQH QBG7 rdSize 
Q@2FC rdFunction (CreateBrush) 
GOOG OOFF OOFF BBVS rdParm (LOGBRUSH structure defining the brush) 


BOZO BOG4 rdSize 
G12D rdFunction (SelectObject) 
0001 rdParm (index to object #1... the brush) 


QQVB BVR7 rdSize 

O41B rdFunction (Rectangle) 

0846 9896 BBBB BYSB rdParm (parameters sent to Rectangle... 
in reverse order) 


QQOB BVSC rdSize 
Q521 rdFunction (TextOut) 
rdParm 
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QQBC count 

string 

48 65 6C 6C 6F 28 58 65 6F 78 6C 65 "Hello People" 
QOBA y-value 

QOBA x-value 


9.6 Summary 


Windows files store information required to create Windows applications as well 
as data needed by the Windows system and Windows applications during execu- 
tion. For more information on topics related to Windows files, see the following: 


Topic Reference 


Metafile functions Reference, Volume I: Chapter 1, “Window 
Manager Interface Functions,” and Chapter 
4, “Functions Directory” 


Device-independent bitmaps Guide to Programming: Chapter 11, 


“Bitmaps” 
Windows clipboard Guide to Programming: Chapter 13, “The 
Clipboard” 
Creating icons and cursors Tools: Chapter 4, “Designing Images: 


SDKPaint” 


Chapter 


10 


Module-Definition 
Statements 


This chapter describes the statements contained in the module-definition file 
that defines the application’s contents and system requirements for the LINK 
program. LINK links compiled source files with Microsoft Windows and other 
libraries to create an executable Windows application. For information on run- 
ning LINK, see Tools. 


The module-definition file contains one or more of the following module state- 
ments: 


Statement Description 

CODE Code-segment attributes 

DATA Data-segment attributes 
DESCRIPTION One-line description of the module 
EXETYPE -EXE header type (Windows or OS/2) 
EXPORTS Exported functions 

HEAPSIZE Size of local heap in bytes 
IMPORTS Imported functions 

LIBRARY Dynamic-link library name 
NAME Module name 

SEGMENTS Additional code segment 
STACKSIZE Size of local stack in bytes 

STUB Old-style executable 


This chapter describes these statements, their syntax, required and optional 
parameters, and usage. 


CODE 
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CODE 
Syntax 


Comments 


Example 


DATA 
Syntax 


CODE [FIXEDIMOVEABLE] [DISCARDABLE] [\PRELOADILOADONCALL] 


This statement defines the attributes of the standard code segment. The standard code seg- 
ment is the application segment having the name _TEXT and belonging to the class 
CODE. In C applications, the standard data segment is created automatically if no specific 
segment name is included in the C-Compiler command line. 


The FIXED option, if included, means that the segment remains at a fixed memory loca- 
tion; the MOVEABLE option means that the segment can be moved, if necessary, in order 


to compact memory. 


The DISCARDABLE option, if included, means that the segment can be discarded if it is 
no longer needed. 


The PRELOAD option, if included, means that the segment is loaded when the module is 
first loaded; the LOADONCALL option means that the segment is loaded when it is 
called. The Resource Compiler may override this option. See Jools for more information. 


There are no default attributes for code segments. The .DEF file should always explicitly 
define code-segment attributes. 


If conflicting options are included in the same statement, LINK uses the overriding option 
to determine the segment attributes. The following list shows which options override 
which: 

MOVEABLE overrides FIXED. 

PRELOAD overrides LOADONCALL. 


CODE MOVEABLE LOADONCALL 


In this example, the loader forces all fixed and moveable (but not discardable) data 
segments to be loaded. Libraries cannot have code that is moveable but not discardable. 


DATA [[NONEISINGLEIMULTIPLE] [FIXEDIMOVEABLE] 


This statement defines the attributes of the standard data segment. The standard data seg- 
ment is all application segments belonging to the group DGROUP and the class DATA. In 
C applications, the standard data segment is created automatically. The data is always pre- 
loaded. 


DESCRIPTION 
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The NONE option, if included, means that there is no data segment. To be effective, this 
option should be the only attribute of the segment. This option is available only for librar- 
ies. 
The SINGLE option, if included, means that a single segment is shared by all instances of 
the module, and is valid only for libraries. 
The MULTIPLE option means that one segment exists for each instance, and is only valid 
for applications. 
NONE, SINGLE, and MULTIPLE are mutually exclusive. 
The FIXED option, if included, means that the segment remains at a fixed memory loca- 
tion. The MOVEABLE option means that the segment can be moved if necessary, in order 
to compact memory. . 
Comments There are no default attributes for data segments. The .DEF file should always explicitly 
define data-segment attributes. 
Data segments are always preloaded. 
If conflicting options are included in the same statement, LINK uses the overriding option 
to determine the segment attributes. The following list shows which options override 
which: 
MULTIPLE overrides NONE. 
SINGLE overrides NONE. 
MOVEABLE overrides FIXED. 
Example DATA MOVEABLE SINGLE 
This example tells LINK that this module has a single, moveable data segment. 
DESCRIPTION 
Syntax DESCRIPTION ‘tex?’ 


This statement inserts text into the application’s module. It is useful for embedding source- 
control or copyright information. 


Parameter Description 


text Specifies one or more ASCII characters. The string must be en- 
closed in single quotation marks. 
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Example DESCRIPTION ‘Microsoft Windows Template Application’ 


This example embeds the text “Microsoft Windows Template Application” in the applica- 
tion module. 


EXETYPE 


Syntax EXETYPE headertype 
This statement specifies the default executable-file (EXE) header type (Windows or 
OS/2). It is required for every Windows application. 
Parameter Description 
headertype Determines the header type. When linking an application in- 
tended for the Windows environment, you must set this 
parameter to the value “WINDOWS”. For an MS OS/2 applica- 
tion, set this parameter to the value “OS/2”. 
Example EXETYPE WINDOWS 
EXPORTS 
Syntax EXPORTS exportname [ordinal-option] [\res-option]] [data-option] [[parameter-option] 


This statement defines the names and attributes of the functions to be exported to other 
applications. The EXPORTS key word marks the beginning of the definitions. It can be 
followed by any number of export definitions, each on a separate line. 


Parameter Description 


exportname Specifies one or more ASCII characters that define the function 
name. It has the following form: 


<entryname>=[internalname] 


where the entryname parameter specifies the name to be used by 
other applications to access the exported function, and internal- 
name is an optional parameter that defines the actual name of 
the function if entryname is not the actual name. 


ordinal-option Defines the function’s ordinal value. It has the following form: 
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HEAPSIZE 


Example 


HEAPSIZE 
Syntax 


Parameter Description 
@ordinal 


where ordinal takes an integer value that specifies the function’s 
ordinal value. The ordinal value defines the location of the func- 
tion’s name in the application’s string table. (When exporting 
functions from libraries, it is better to use an ordinal rather than 
a name; using ordinals conserves space.) 


res-option Is the optional key word RESIDENTNAME, which specifies 
that the function’s name must be resident at all times. 


data-option Is the optional key word NODATA, which specifies that the 
function is not bound to a specific data segment. When invoked, 
the function uses the current data segment. 


parameter-option Is an optional integer value that specifies the number of words 
the function expects to be passed as parameters. 


EXPORTS 
SampleRead=read2bin @1 8 
StringIn=strl @2 4 
CharTest NODATA 


This example exports the functions SampleRead, StringIn and CharTest so that other appli- 
cations, or Windows itself, can call them. 


HEAPSIZE bytes 


This statement defines the number of bytes needed by the application for its local heap. An 
application uses the local heap whenever it allocates local memory. 


The default heap size is zero. The minimum size is 256 bytes. For an application, the size 
of the local heap must be at least large enough to hold the current environment. 
Parameter Description 


bytes Is an integer value that specifies the heap size in bytes. It must 
not exceed 65,536 (the size of a single physical segment). 
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Example HEAPSIZE 4096 


This example sets the size of the application’s local heap to 4096 bytes. 


IMPORTS 
Syntax IMPORTS [internal-option]] modulename [[entry-option] 


This statement defines the names and attributes of the functions to be imported from dy- 
namic-link libraries. The IMPORTS key word marks the beginning of the definitions. It 
can be followed by any number of import definitions, each on a separate line. 


Parameter . Description 


internal-option Specifies the name that the application will use to call the func- 
tion. It has the following form: 


internal-name= 


where internal-name is one or more ASCII characters. This 
name must be unique. 


modulename Specifies one or more uppercase ASCII characters that define 
the name of the executable module that contains the function. 
The module name must match the name of the executable file. 
For example, an application with the executable file 
SAMPLE.DLL has the module name “SAMPLE”. The exe- 
cutable file must be named with the .DLL extension. 


entry-option Specifies the function to be imported. It can be one of the follow- 
ing: 


_ .entryname 
.entryordinal 


where entryname is the actual name of the function, and entry- 
ordinal is the ordinal value of the function. 


Example IMPORTS 
Sample.SampleRead 
write2hex=Sample.SampleWrite 
Read.1 
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LIBRARY 


LIBRARY 
Syntax 


Comments 


Example 


NAME 
Syntax 


NOTE \nstead of listing imported DLL functions in the IMPORTS statement, you can specify an “im- 
port library” for the DLL in your application’s LINK command line. It also saves space to import by ordi- 
nal. 


LIBRARY libraryname 


This statement defines the name of a library module. Library modules are resource mod- 
ules that contain code, data, and other resources but are not intended to be executed as an 
independent program. Like an application’s module name, a library’s module name must 
match the name of the executable file. For example, the library USER.EXE has the module 
name “USER”. 


Parameter Description 


libraryname Specifies one or more ASCII characters that define the name of 
the library module. 


The start address of the library module is determined by the library’s object files; it is an in- 
ternally defined function. 


The libraryname parameter is optional. If the parameter is not included, LINK uses the 
filename part of the executable file (that is, the name with the extension removed). 


If the .DEF file includes neither a NAME nor a LIBRARY statement, LINK assumes a 
NAME statement without a modulename parameter is desired. 
LIBRARY Utilities 


This example gives a library the module name “Utilities.” 


NAME modulename 


This statement defines the name of the application’s executable module. The module name 
identifies the module when exporting functions. 
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Parameter Description 


modulename Specifies one or more uppercase ASCII characters that define 
the name of the executable module. The module name must 
match the name of the executable file. For example, an applica- 
tion with the executable file SAMPLE.EXE has the module 
name “SAMPLE”. 


Comments The modulename parameter is optional. If the parameter is not included, LINK assumes 
that the module name matches the the filename of the executable file. For example, if you 
do not specify a module name and the executable file is named MYAPP.EXE, LINK as- 
sumes that the module name is “MYAPP”’. 


If the .DEF file includes neither a NAME nor a LIBRARY statement, LINK assumes a 
NAME statement without a modulename parameter is desired. 


Example NAME Calendar 


This example gives an application the module name “Calendar”. 


SEGMENTS 


Syntax SEGMENTS segmentname [CLASS ’class-name’] [minalloc]\\ 
[FIXEDIMOVEABLE] 
[DISCARDABLE] [SHAREDINONSHARED] [PRELOADILOADONCALL] 


This statement defines the segment attributes of additional code and data segments. 


The FIXED option, if included, means that the segment remains at a fixed memory loca- 
tion. The MOVEABLE option means that the segment can be moved if necessary, in order 
to compact memory. 


The DISCARDABLE option, if included, means that the segment can be discarded if it is 
no longer needed. 


The PRELOAD option, if included, means that the segment is loaded immediately The 
LOADONCALL option means that the segment is loaded when it is accessed or called. 
The Resource Compiler may override this option. See Jools for more information. 


Parameter Description 


segmentname Specifies a character string that names the new segment. It can 
be any name, including the standard segment names _TEXT and 
_DATA, which represent the standard code and data segments. 
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Parameter Description 


class-name Is an optional key word that specifies the class name of the 
specified segment. If no class name is specified, LINK uses the 
class name CODE by default. 


minalloc Is an optional integer value that specifies the minimum alloca- 
tion size for the segment. 


Comments There are no default attributes for additional segments. The .DEF file should always expli- 
citly define the attributes of additional segments. 


If conflicting options are included in the same statement, LINK uses the overriding option 
to determine the segment attributes. The following list shows which options override 
which: 

MOVEABLE overrides FIXED. 

PRELOAD overrides LOADONCALL. 


Example SEGMENTS 
_TEXT FIXED 
_INIT PRELOAD DISCARDABLE 
_RES CLASS 'DATA' PRELOAD DISCARDABLE 


STACKSIZE 
Syntax STACKSIZE bytes 


This statement defines the number of bytes needed by the application for its local stack. An 
application uses the local stack whenever it makes function calls. 


The default stack size is zero if the application makes no function calls. If your application 
does make function calls and you specify a stack size smaller than 5K bytes, Windows au- 
tomatically sets the stack size to 5K bytes. 


Parameter Description 


bytes Is an integer value that specifies the stack size in bytes. 


Comments Do not use the STACKSIZE statement for dynamic-link libraries. 


STUB 
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Example 


STUB 
Syntax 


Comments 


Example 


STACKSIZE 6144 


This example sets the size of an application’s stack to 6144 bytes. 


STUB ‘filename’ 


This statement appends the old-style executable file specified by filename to the beginning 
of the module. The executable stub should display a warning message and terminate if the. 
user attempts to execute the module without having loaded Windows. The default file 
WINSTUB.EXE can be used if no other actions are required. 


Parameter Description 

filename Specifies the name of the old-style executable file that will be 
appended to the module. The name must have the DOS filename 
format. 


If the file named by filename is not in the current directory, LINK searches for the file in 
the directories specified by the user’s PATH environment variable. 


STUB 'WINSTUB.EXE' 


This example specifies the executable file WINSTUB.EXE as the application’s stub. If a 
user tries to run this application in the DOS environment, rather than with Windows, the 
program WINSTUB.EXE starts instead. 


Chapter || Binary and Ternary 
17 Raster-Operation Codes 


This chapter lists and describes the binary and ternary raster operations used by 
the graphics device interface (GDI). A binary raster operation uses two operands: 
a pen and a destination bitmap. A ternary raster operation uses three operands: a 
source bitmap, a brush, and a destination bitmap. Both binary and ternary raster 
operations use Boolean operators. 


11.1 Binary Raster Operations 


This section lists the binary raster-operation codes used by the GetROP2 and 
SetROP2 functions. Raster-operation codes define how GDI combines the bits 
from the selected pen with the bits in the destination bitmap. 


Each raster-operation code represents a Boolean operation in which the selected 
pen and the destination bitmap are combined. There are two operands used in 
these operations: 


D Destination bitmap 


Pp Selected pen 


The Boolean operators used in these operations are as follows: 


a Bitwise AND 

n Bitwise NOT (inverse) 

fe) Bitwise OR 

X Bitwise Exclusive OR (XOR) 


All Boolean operations are presented in reverse Polish notation. For example, the 
following operation replaces the destination with a combination of the pen and 
the selected brush: 


DPo 
Each raster-operation code is a 32-bit integer value whose high-order word is a 


Boolean operation index and whose low-order word is the operation code. The 
16-bit operation index is a zero-extended 8-bit value that represents the result of 
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the Boolean operation on predefined pen and destination values. For example, 
the operation indexes for the DPo and DPan operations are shown in Table 11.1: 


Table 11.1 Operation Indexes for DPo and DPan 


P D PSo DPSoo 
0 0 0 1 
0 1 1 1 
1 0 1 1 
1 1 1 0 


The following list outlines the drawing modes and the Boolean operations that 
they represent: 


Raster Operation Boolean Operation 
R2_BLACK 0 
R2_COPYPEN P 
R2_MASKNOTPEN DPna 
R2_MASKPEN DPa 
R2_MASKPENNOT PDna 
R2_MERGENOTPEN DPno 
R2_MERGEPEN DPo 
R2_MERGEPENNOT PDno 
R2_NOP D 
R2_NOT Dn 
R2_NOTCOPYPEN Pn 
R2_NOTMASKPEN DPan 
R2_NOTMERGEPEN DPon 
R2_NOTXORPEN DPxn 
R2_WHITE 1 
R2_XORPEN DPx 


When a monochrome device is used, GDI maps the value zero to black and the 
value | to white. Given an application that attempts to draw with a black pen on 


a white destination by using the available binary raster operations, the following 


results will occur: 


Raster Operation 
R2_BLACK 
R2_COPYPEN 
R2_MASKNOTPEN 
R2_MASKPEN 
R2_MASKPENNOT 
R2_MERGENOTPEN 
R2_MERGEPEN 
R2_MERGEPENNOT 
R2_NOP 

R2_NOT 
R2_NOTCOPYPEN 
R2_NOTMASKPEN 
R2_NOTMERGEPEN 
R2_NOTXORPEN 
R2_WHITE 
R2_XORPEN 
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Visible black line 
Visible black line 
No visible line 
Visible black line 
Visible black line 
No visible line 
Visible black line 
Visible black line 
No visible line 
Visible black line 
No visible line 
No visible line 
Visible black line 
Visible black line 
No visible line 


No visible line 


When a color device is used, GDI uses RGB values to represent the colors of the 
pen and the destination. An RGB color value is a long integer that contains a red, 
a green, and a blue color field, each specifying the intensity of the given color. In- 
tensities range from 0 to 255. The values are packed in the three low-order bytes _. 
of the long integer. The color of a pen is always a solid color, but the color of the 
destination may be a mixture of any two or three colors. Given an application — 
that attempts to draw with a white pen on a blue destination by using the availa- 
ble binary raster operations, the following results will occur: . 


Raster Operation Result 
R2_ BLACK Visible black line 
R2_COPYPEN : Visible white line 


R2_MASKNOTPEN Visible black line 
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Raster Operation 
R2_MASKPEN 
R2_MASKPENNOT 
R2_MERGENOTPEN 
R2_MERGEPEN 
R2_MERGEPENNOT 
R2_NOP 

R2_NOT 
R2_NOTCOPYPEN 
R2_NOTMASKPEN 
R2_NOTMERGEPEN 
R2_NOTXORPEN 
R2_WHITE 
R2_XORPEN 


Invisible blue line 
Visible red/green line 
Invisible blue line 
Visible white line 
Visible white line 
Invisible blue line 
Visible red/green line 
Visible black line 
Visible red/green line 
Visible black line 
Invisible blue line 
Visible white line 


Visible red/green line 


11.2 Ternary Raster Operations 


This section lists the ternary raster-operation codes used by the BitBlt, PatBlt, 
and StretchBlt functions. Ternary raster-operation codes define how GDI com- 
bines the bits in a source bitmap with the bits in the destination bitmap. 


Each raster-operation code represents a Boolean operation in which the source, 
the selected brush, and the destination bitmap are combined. There are three oper- 
ands used in these operations: 

Destination bitmap 


P Selected brush (also called pattern) 


Source bitmap 


The Boolean operators used in these operations are as follows: 


a Bitwise AND 
n Bitwise NOT (inverse) 
oO Bitwise OR 


X Bitwise Exclusive OR (XOR) 
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All Boolean operations are presented in reverse Polish notation. For example, the 
following operation replaces the destination with a combination of the source and 
brush: 


PSo 


The following operation combines the source and brush with the destination 
(there are alternate spellings of the same function, so although a particular spel- 
ling may not be in the list, an equivalent form will be): 


DPSoo 


Each raster-operation code is a 32-bit integer value whose high-order word is a 
Boolean operation index and whose low-order word is the operation code. The 
16-bit operation index is a zero-extended, 8-bit value that represents the result of 
the Boolean operation on predefined brush, source, and destination values. For 
example, the operation indexes for the PSo and DPSoo operations are shown in 
Table 11.2: 


Table 11.2 Operation Indexes for PSo and DPSoo 


P S D PSo DPSoo 
0 0 0 0 0 

0 0 1 0 l 

0 1 0 1 1 

0 1 l 1 1 

1 0 0 1 1 

1 0 1 ] 1 

l 1 0 1 1 

1 1 1 1 l 
Operation index: O0OFC OOFE 


In this case, PSo has the operation index OOFC (read from the bottom up); DPSoo 
has the operation index OOFE. These values define the location of the correspond- 
ing raster-operation codes, as shown in Table 11.1, “Operation Indexes for DPo 
and DPan.” The PSo operation is in line 252 (FCh) of the table; DPSoo is in line 
254 (FEh). 


The most commonly used raster operations have been given special names in the 
Windows include file, WINDOWS.H. You should use these names whenever 
possible in your applications. 


When the source and destination are monochrome, a bit value of zero represents 
a black pixel and a bit value of 1 represents a white pixel. When the source and 
the destination are color, those colors are represented with RGB values. For more 
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information about RGB values, see the RGB structure in Chapter 7, “Data Types 
and Structures.” 


Table 11.3 lists the raster-operation codes: 


Table 11.3 Raster-Operation Codes 


Boolean Hex Boolean Common 
Function ROP Function Name 
in Hex in Reverse Polish 

00 00000042 0 BLACKNESS 
01 00010289 DPSoon - 

02 00020C89 DPSona - 

03 000300AA PSon - 

04 00040C88 SDPona - 

05 000500A9 DPon - 

06 00060865 PDSxnon - 

07 000702C5 PDSaon - 

08 O0080F08 SDPnaa - 

09 00090245 PDSxon - 

0A 000A0329 DPna - 

OB O0O0O0BOB2A PSDnaon - 

OC 000C0324 SPna - 

0D 000D0B25 PDSnaon - 

OE OOOEO8A5 PDSonon - 

OF 000FO001 Pn - 

10 00100C85 PDSona - 

11 001100A6 DSon NOTSRCERASE 
12 00120868 SDPxnon - 

13 001302C8 SDPaon - 

14 00140869 DPSxnon - 

15 001502C9 DPSaon - 

16 00165CCA PSDPSanaxx - 

17 00171D54 SSPxDSxaxn - 

18 00180D59 SPxPDxa - 

19 00191CC8 SDPSanaxn - 

1A 001A06C5 PDSPaox - 

1B 001B0768 SDPSxaxn - 

1C 001C06CA PSDPaox - 


Table 11.3 


Boolean 
Function 
in Hex 


1D 
1E 
1F 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
2A 
2B 
2C 
2D 
2E 
2F 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
3A 
3B 
3C 
3D 
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Hex 
ROP 


001D0766 
001E01A5 
001F0385 
00200F09 
00210248 
00220326 
00230B24 
00240D55 
00251CCS5 
002606C8 
00271868 
00280369 
002916CA 
002A0CC9 
002B1D58 
002C0784 
002D060A 
002E064A° 
O002FOE2A 
0030032A 
00310B28 
00320688 
00330008 
003406C4 
00351864 
003601A8 
00370388 


0038078A ° 


00390604 

003A0644 
003B0E24 
003C004A 
003D18A4 


Raster-Operation Codes (continued) 


Boolean 
Function 


in Reverse Polish 


DSPDxaxn 
PDSox 
PDSoan 
DPSnaa 
SDPxon 
DSna 
SPDnaon 
SPxDSxa 
PDSPanaxn 
SDPSaox 
SDPSxnox 
DPSxa 
PSDPSaoxxn 
DPSana_ 
SSPxPDxaxn 
SPDSoax 
PSDnox 
PSDPxox 
PSDnoan 
PSna 
SDPnaon 
SDPSoox 
Sn 
SPDSaox 
SPDSxnox 
SDPox 
SDPoan 
PSDPoax 
SPDnox 
SPDSxox 
SPDnoan 
PSx 
SPDSonox 


Common 
Name 


NOTSRCCOPY 
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Table 11.3 Raster-Operation Codes (continued) 


Boolean Hex Boolean Common 
Function ROP Function Name 

in Hex in Reverse Polish 

3E 003E1B24 SPDSnaox - 

3F 003FOOEA PSan - 

40 00400F0A PSDnaa - 

41 00410249 DPSxon - 

42 00420D5D SDxPDxa - 

43 00431CC4 SPDSanaxn - 

44 00440328 SDna SRCERASE 
45 00450B29 DPSnaon - 

46 004606C6 DSPDaox - 

47 0047076A PSDPxaxn - 

48 00480368 SDPxa - 

49 004916C5 PDSPDaoxxn - 

4A 004A0789 DPSDoax - 

4B 004B0605 PDSnox - 

4C 004C0CC8 SDPana - 

4D 004D1954 SSPxDSxoxn .- - 

4E 004E0645 PDSPxox - 

4F 004FOE25 PDSnoan - 

50 00500325 PDna - 

51 00510B26 DSPnaon - 

52 005206C9 DPSDaox - 

53 00530764 SPDSxaxn - 

54 005408A9 DPSonon - 

25 00550009 Dn DSTINVERT 
56 005601A9 DPSox - 

ay) 00570389 DPSoan - 

58 00580785 PDSPoax - 

59 00590609 DPSnox - 

SA 005A0049 DPx PATINVERT 
5B 00SB18A9 DPSDonox - 

5C 005C0649 DPSDxox - 

5D OOSDOE29 DPSnoan - 

SE 00S5SE1B29 DPSDnaox - 


Table 11.3 


Boolean 
Function 
in Hex 


oF 
60 
61 


Hex 
ROP 


005FOOE9 
00600365 
006116C6 
00620786 
00630608 
00640788 
00650606 
00660046 
006718A8 
006858A6 
00690145 
006A01E9 
006B178A 
006C01E8 
006D1785 
006E1E28 
006FOC65 
00700CC5 
00711D5C 
00720648 
00730E28 
00740646 


00750E26 


00761B28 
007700E6 
007801ES5 
00791786 
OO7ALE29 
007B0C68 
007C1E24 
007D0C69 
007E0955 
007F03C9 


Raster-Operation Codes (continued) 


Boolean 
Function 


in Reverse Polish 


DPan 

PDSxa 
DSPDSaoxxn 
DSPDoax 
SDPnox 
SDPSoax 
DSPnox 

DSx 
SDPSonox 


DSPDSonoxxn 


PDSxxn 
DPSax 
PSDPSoaxxn 
SDPax 
PDSPDoaxxn 
SDPSnoax 
PDSxnan 
PDSana 
SSDxPDxaxn 
SDPSxox 
SDPnoan 
DSPDxox 
DSPnoan 
SDPSnaox 
DSan 

PDSax 
DSPDSoaxxn 
DPSDnoax 
SDPxnan 
SPDSnoax 
DPSxnan 
SPxDSxo 
DPSaan 
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SRCINVERT 
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Table 11.3 Raster-Operation Codes (continued) 


Boolean Hex Boolean Common 
Function ROP Function Name 
in Hex in Reverse Polish 

80 008003E9 DPSaa - 
81 00810975 SPxDSxon - 
82 00820C49 DPSxna - 
83 0083 1E04 SPDSnoaxn - 
84 00840C48 SDPxna : 
85 00851E05 PDSPnoaxn - 
86 008617A6 DSPDSoaxx - 
87 008701C5 PDSaxn - 
88 008800C6 DSa SRCAND 
89 00891B08 SDPSnaoxn - 
8A OO8A0E06 DSPnoa - 
8B 008B0666 DSPDxoxn - 
8C O08COE08 SDPnoa - 
8D 008D0668 SDPSxoxn - 
8E 008E1D7C SSDxPDxax - 
8F OO8FOCES PDSanan - 
90 00900C45 PDSxna - 
91 00911E08 SDPSnoaxn - 
92 009217A9 DPSDPoaxx - 
93 009301C4 SPDaxn - 
94 009417AA PSDPSoaxx - 
95 009501C9 DPSaxn - 
96 00960169 DPSxx - 
97 0097588A PSDPSonoxx - 
98 00981888 SDPSonoxn - 
99 00990066 DSxn - 
9A 009A0709 DPSnax - 
9B 009B07A8 SDPSoaxn - 
9C 009C0704 SPDnax - 
9D 009D07A6 DSPDoaxn - 
9E 009E16E6 DSPDSaoxx - 
OF 009F0345 PDSxan - 
AO OOA000C9 DPa - 


Table 11.3 


Boolean 
Function 
in Hex 


Al 
A2 
A3 
A4 
AS 
A6 
A7 
A8 
A9 
AA 
AB 
AC 
AD 
AE 
AF 
BO 
Bl 
B2 
B3 
B4 
BS 
B6 
B7 
B8 
B9 
BA 
BB 
BC 
BD 
BE 
BF 
CO 
Cl 
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Hex 
ROP 


00A11B05 
00A20E09 
00A30669 
00A41885 
00A50065 
00A60706 
00A707A5 
00A803A9 
00A90189 
00AA0029 
O00AB0889 
00AC0744 
OOADO6E9 
OOAEOB06 
OOAF0229 
OOBOOE0S 
00B 10665 
00B21974 
00B30CE8 
00B4070A 
00B507A9 
O0B616E9 
00B70348 
00B8074A 


- 00B906E6 


0O0BAOB09 
00BB0226 
0O0BC1CE4 
0OBDOD7D 
O0O0BE0269 
OOBFO8C9 
00CO00CA 
00C11B04 


Raster-Operation Codes (continued) 


Boolean 
Function 


in Reverse Polish 


PDSPnaoxn 
DPSnoa 
DPSDxoxn 
PDSPonoxn 
PDxn 
DSPnax 
PDSPoaxn 
DPSoa 
DPSoxn 

D 

DPSono 
SPDSxax 
DPSDaoxn 
DSPnao 
DPno 
PDSnoa 
PDSPxoxn 
SSPxDSxox 
SDPanan 
PSDnax 
DPSDoaxn 
DPSDPaoxx 
SDPxan 
PSDPxax 
DSPDaoxn 
DPSnao 
DSno 
SPDSanax 
SDxPDxan 
DPSxo 
DPSano 
PSa 
SPDSnaoxn 


Common 
Name 


MERGEPAINT 


MERGECOPY 
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Table 11.3 Raster-Operation Codes (continued) 


Boolean Hex Boolean Common 
Function ROP Function Name 
in Hex in Reverse Polish 

C2 00C21884 SPDSonoxn - 
C3 00C3006A PSxn - 
C4 00C40E04 SPDnoa - 
C5 00C50664 SPDSxoxn - 
C6 00C60708 SDPnax - 
C7 00C707AA PSDPoaxn - 
C8 00C803A8 SDPoa - 
C9 00C90184 SPDoxn - 
CA 00CA0749 DPSDxax - 
CB OO0CBO6E4 SPDSaoxn - 
CC 00CC0020 S SRCCOPY 
CD OOCD0888 SDPono - 
CE OOCEOB08 SDPnao - 
CF O0O0CF0224 SPno - 
DO OODOOEOA PSDnoa - 
D1 00D1066A PSDPxoxn - 
D2 00D20705 PDSnax - 
D3 00D307A4 SPDSoaxn - 
D4 00D41D78 SSPxPDxax - 
D5 00DSOCE9 DPSanan - 
D6 OOD616EA PSDPSaoxx - 
D7 00D70349 DPSxan : 
D8 00D80745 PDSPxax - 
D9 OOD906E8 SDPSaoxn - 
DA O0ODA1CE9 DPSDanax - 
DB OODBOD75 SPxDSxan - 
DC 00DCOB04 SPDnao - 
DD 00DD0228 SDno - 
DE O0ODE0268 SDPxo - 
DF OODFO8C8 SDPano - 
EO 00E003A5 PDSoa - 
El 00E10185 PDSoxn : 
E2 00E20746 DSPDxax - 


Table 11.3 


Boolean 
Function 
in Hex 


E3 


Binary and Ternary Raster-Operation Codes 11-13 


Hex 
ROP 


00E306EA 
00E40748 
00ES06ES5 
00E61CE8 
00E70D79 
00E81D74 
00E95CE6 
00EA02E9 
00EB0849 
00EC02E8 
00ED0848 
00EE0086 
OOEFOA08 
00F00021 
OOF10885 
00F20B05 
00F3022A 
O0F40B0A 
00F50225 
00F60265 
O0F708C5 
O0F802E5 
O0F90845 
00FA0089 
OOFBOA09 
OOFCOO8A 
OOFDOA0A 
OOFE02A9 
OOFF0062 


Raster-Operation Codes (continued) 


Boolean 
Function 


in Reverse Polish 


PSDPaoxn 
SDPSxax 
PDSPaoxn 
SDPSanax 
SPxPDxan 
SSPxDSxax 
DSPDSanaxxn 
DPSao 
DPSxno 
SDPao 
SDPxno 
DSo 
SDPnoo 

P 

PDSono 
PDSnao 
PSno 
PSDnao 
PDno 
PDSxo 
PDSano 
PDSao 
PDSxno 
DPo 
DPSnoo 
PSo 
PSDnoo 
DPSoo 

1 


Common 
Name 


SRCPAINT 


PATCOPY 


PATPAINT 


WHITENESS 
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77.3 Summary 


Raster-operation codes define how GDI combines the bits of a source bitmap 
with the bits of a destination bitmap. For more information on topics related to 
raster-operation codes, see the following: 


Topic Reference 

Using raster-operation Reference, Volume 1: Chapter 2, “Graphics 

codes with GDI functions Device Interface Functions,” and Chapter 4, : 
“Functions Directory” 

Setting the current drawing Reference, Volume 1: Chapter 4, “Functions 

mode with SetROP2 Directory” 


Guide to Programming: Chapter 6, “The 
Cursor, the Mouse, and the Keyboard” 


Bitmaps and raster Guide to Programming: Chapter 11, 
operations “Bitmaps” 


Chapter 


12 


Printer Escapes 


This chapter contains an alphabetical list of the individual Microsoft Windows 
printer escapes. The printer escapes allow applications to access facilities of a 
particular output device that are not available directly through the graphics 
device interface (GDI). The escape calls are made by an application, translated 
by Windows, and then sent to the printer device driver. 
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ABORTDOC 
Syntax short Escape(4DC, ABORTDOC, NULL, NULL, NULL) 


This escape terminates the current job, erasing everything the application has written to the 
device since the last ENDDOC escape. 


The ABORTDOC escape should be used to terminate: 
= Printing operations that do not specify an abort function using the SETABORTPROC 
escape 


m Printing operations that have not yet reached their first NEWFRAME or NEXT- 
BAND escape call 


Parameter Type/Description 


hDC HDC _ Identifies the device context. 


Return Value The return value specifies the outcome of the escape. It is positive if the escape is success- 
ful. Otherwise, it is negative. 


Comments If an application encounters a printing error or a canceled print operation, it must not at- 
tempt to terminate the operation by using the Escape function with either the ENDDOC 
or ABORTDOC escape. GDI automatically terminates the operation before returning the 
error value. 


If the application displays a dialog box to allow the user to cancel the print operation, it 
‘must send the ABORTDOC escape before destroying the dialog box. 


The application must send the ABORTDOC escape before freeing the procedure-instance 
address of the abort function, if any. 


BANDINFO 
Syntax short Escape(hDC, BANDINFO, sizeof(BANDINFOSTRUCT), /[pInData, lpOutData) 
This escape copies information about a device with banding capabilities to a structure 


pointed to by the /pOutData parameter. It is implemented only for devices that use band- 
ing. 


Banding is a property of an output device that allows a page of output to be stored in a 
metafile and divided into bands, each of which is sent to the device to create a complete 


page. 
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BANDINFO 


Return Value 


Comments 


The information copied to the structure pointed to by /pOutData includes: 


= A value that indicates whether there are graphics in the next band 
= A value that indicates whether there is text on the page 


= A RECT data structure that contains a bounding rectangle for all graphics on the page 


The /pOutData parameter is NULL if no data are returned. 


The /pInData parameter specifies information sent by the application to the device driver. 
This information is read by the device driver only on the first BANDINFO escape call on 
a page. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpInData BANDINFOSTRUCT FAR * Points toa BANDINFOSTRUCT 


data structure that contains information to be passed to the driver. See 
the following “Comments” section for more information on the BAND- 
INFOSTRUCT data structure. 


IpOutData BANDINFOSTRUCT FAR * Points toa BANDINFOSTRUCT 
data structure that contains information returned by the driver. See the 
following “Comments” section for more information on the BAND- 
INFOSTRUCT data structure. 


The return value specifies the outcome of the escape. It is 1 if the escape is successful. It is 
zero if the function fails or is not implemented by the driver. . 


The BANDINFOSTRUCT data structure contains information about the contents of a 
page and supplies a bounding rectangle for graphics on the page. The following shows the 
format of BANDINFOSTRUCT: 


typedef struct { 
BOOL fGraphicsFlag; 
BOOL fTextFlag; 
RECT  GraphicsRect; 
} BANDINFOSTRUCT; 


The BANDINFOSTRUCT structure has the following fields: 
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Field Description 


fGraphicsFlag Is TRUE if graphics are or are expected to be on the page or in 
the band; otherwise, it is FALSE. 


fTextFlag Is TRUE if text is or is expected to be on the page or in the 
band; otherwise, it is FALSE. 


GraphicsRect Contains a RECT data structure that supplies a bounding region 
for all graphics on the page. 


Table 12.1 shows the meaning of these fields, depending on which parameter contains the 
structure. 


Table 12.1 Meaning of BANDINFOSTRUCT Fields © 


Field When Used in /p/nData When Used in /pOutData 

fGraphicsFlag TRUE if the application is inform- TRUE if the driver is informing the 
ing the driver that graphics are on application that it expects graphics 
the page. in this band. 

' fTextFlag TRUE if the application is inform- TRUE if the driver is informing the 
ing the driver that text is on the page. application that it expects text in 
this band. 
GraphicsRect Supplies the bounding rectangle for No valid return data. 
: all graphics on the page. 


An application should call this escape immediately after each call to the NEXTBAND 
escape. It is in reference to the band the driver returned to that escape. 


An application should use this escape in the following manner: 


On the first band, the driver may give the application a full-page band and ask for text only 
(fGraphicsFlag is set to FALSE and fTextFlag is set to TRUE). The application sends 
only text to the driver. 


If in the first band the application indicated that it had graphics (fGraphicsFlag is set to 
TRUE), or that the driver encountered vector fonts, then the driver will band the rest of the 
page. If there are no graphics or vector fonts, then the next NEXTBAND will return an 
empty rectangle to indicate that the application should move on to the next page. 


If there are graphics but no vector fonts (the application set fGraphicsFlag to TRUE, but 
there were no graphics in the first full-page text band), then for subsequent bands the 
driver may optionally band only into the rectangle the application passed. This rectangle 
bounds all graphics on the page. If there are vector fonts, then the driver will band the en- 
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BEGIN PATH 


BEGIN_PATH 
Syntax | 


Return Value 


Comments 


tire width and depth of the page with fTextFlag set to TRUE. It will also set fGraphics- 
Flag to true if the application set it. 


The driver assumes that an application using BANDINFO will only send text in the first 
full-page text band since that is all the driver requested. Therefore, if the driver encounters 
a vector font or graphics in the band, it assumes they were generated by a text primitive 
and sets fTextFlag to TRUE for all subsequent graphics bands so they can be output as 
graphics. If the application does not satisfy this expectation, the image will still be 
generated properly, but the driver will spend time sending spurious text primitives to 
graphics bands. 


Older drivers written before the BANDINFO escape was designed used full-page banding 
for text. If a particular driver does not support the BANDINFO escape but sets 
RC_BANDING, the application can detect full-page banding for text by determining if the 
first band on the page covers the entire page. 


short Escape(i4DC, BEGIN_PATH, NULL, NULL, NULL) 


This escape opens a path. A path is a connected sequence of primitives drawn in succes- 
sion to form a single polyline or polygon. Paths enable applications to draw complex 
borders, filled shapes, and clipping areas by supplying a collection of other primitives that 
define the desired shape. 


Printer escapes supporting paths enable applications to render images on sophisticated dev- 
ices such as PostScript® printers without generating huge polygons to simulate the images. 


To draw a path, an application first issues the BEGIN_PATH escape. It then draws the 
primitives defining the border of the desired shape and issues an END_PATH escape. The 
END_PATH escape includes a parameter specifying how the path is to be rendered. 


Parameter Type/Description 


hDC HDC _ Identifies the device context. 


The return value specifies the current path nesting level. If the escape is successful, the re- 
turn value is the number of BEGIN_PATH escape calls without a corresponding 
END_PATH escape call. Otherwise, the return value is zero. 


An application may begin a subpath within another path. If the subpath is closed, it is 
treated exactly like a polygon. If it is open, it is treated exactly like a polyline. 


An application may use the CLIP_TO_PATH escape to define a clipping area correspond- 
ing to the interior or exterior of the currently open path. 
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CLIP_TO_PATH | 
Syntax short Escape(i4DC, CLIP_TO_PATH, sizeof(int), pClipMode, NULL) 


This escape defines a clipping area bounded by the currently open path. It enables the 
application to save and restore the current clipping area and to set up an inclusive or exclu- 
sive clipping area bounded by the currently open path. If the path defines an inclusive clip- 
ping area, portions of primitives falling outside the interior bounded by the path are 
clipped. If the path defines an exclusive clipping area, portions of primitives falling inside 
the interior are clipped. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpClipMode LPINT Points to a short integer specifying the clip- 
ping mode. It can be one of the following values: 
Value Meaning 
CLIP_SAVE (0) Saves the current clip- 
ping area. 
CLIP_RESTORE (1) Restores the previous 
clipping area. 
CLIP_INCLUSIVE (2) Sets an inclusive clipping 
area. 
CLIP_EXCLUSIVE (3) Sets an exclusive clip- 
ping area. . 
Return Value The return value specifies the outcome of the escape. It is nonzero if the escape was 


successful. Otherwise, it is zero. 


Comments To clip a set of primitives against a path, an application should follow these steps: 


41. Save the current clipping area using the CLIP_TO_PATH escape. 
2. Begin a path using the BEGIN_PATH escape. 


3. Draw the primitives bounding the clipping area. 
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4. Set the clipping area using the CLIP_TO_PATH escape. 
5. Close the path using the END_PATH escape. 
6. Draw the primitives to be clipped. 
7. Restore the original clipping area using the CLIP_TO_PATH escape. 
DEVICEDATA 
Syntax short Escape(hDC, DEVICEDATA, nCount, lpInData, [pOutData): 
This escape is identical to the PASSTHROUGH escape. See the description of PASS- 
THROUGH for further information. 
DRAFTMODE 
Syntax short Escape(hADC, DRAFTMODE, sizeof(int), /pDraftMode, NULL) 


Return Value 


Comments 


This escape turns draft mode off or on. Turning draft mode on instructs the device driver to 
print faster and with lower quality (if necessary). The draft mode can be changed only at 
page boundaries, for example, after a NEWFRAME escape directing the driver to ad- 
vance to a new page. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpDraftMode LPINT Points to a short-integer value that specifies the draft 
mode. It may be one of the following values: 
Value Meaning 
0 Specifies draft mode off. 
1 Specifies draft mode on. 


The return value specifies the outcome of the escape. It is positive if the escape is success- 
ful. Otherwise, it is negative. 


The default draft mode is off. 


DRAWPATTERNRECT | ei 


DRAWPATTERNRECT 


Syntax 


Return Value 


Comments 


short Escape(4DC, DRAWPATTERNRECT, sizeof(PRECTSTRUCT), [p/nData, 
NULL) 


This escape creates a pattern, gray scale, or solid black rectangle by using the pattern/rule 

capabilities of Page Control Language (PCL) on Hewlett-Packard® LaserJet® or LaserJet- 
compatible printers. A gray scale is a gray pattern that contains a specific mixture of black 
and white pixels. | 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpInData PRECT_STRUCT FAR * Points toa PRECT_STRUCT 


data structure that describes the rectangle. See the following 
“Comments” section for more information on the 
PRECT_STRUCT data structure. 


The return value specifies the outcome of the escape. It is 1 if the escape is successful. 
Otherwise, it is zero. 


The /pInData parameter points to a PRECT_STRUCT data structure that defines the 
rectangle to be created. The PRECT_STRUCT structure has the following format: 


‘typedef struct { 


POINT prPosition; 

POINT prSize; 

WORD = prStyle; 

WORD ~=prPattern; 
} PRECT_STRUCT; 


This structure has the following fields: 


Field Description 

prPosition Specifies the upper-left corner of the rectangle. 

prSize Specifies the lower-right corner of the rectangle. 

prStyle Specifies the type of pattern. It may be one of the following 


values: 
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Field Description 

Value Meaning 

0 Black rule. 

1 White rule that erases bitmap data previously 
written to same area; this pattern is available on 
the HP LaserJet IIP only. 

a Gray scale. 

3 HP-defined. 

prPattern Specifies the pattern. It is ignored for a black rule. It speci- 

fies the percentage of gray for a gray-scale pattern. It 

represents one of six Hewlett-Packard-defined patterns. 

An application should use the QUERYESCSUPPORT escape to determine whether a 
device is capable of drawing patterns and rules before using the DRAWPATTERNRECT 
escape. If an application uses the BANDINFO escape, all patterns and rectangles sent by 
using DRAWPATTERNRECT should be treated as text and sent on a text band. 
Do not try to erase patterns and rules created with the DRAWPATTERNRECT escape by 
placing opaque objects over them. To erase such patterns and rules, use the function calls 
provided by GDI. 

ENABLEDUPLEX 

Syntax short Escape(hDC, ENABLEDUPLEX, sizeof(WORD), /p/nData, NULL) 


This escape enables the duplex printing capabilities of a printer. A device that possesses du- 
plex printing capabilities is able to print on both sides of the output medium. 


Parameter 


hDC 
lpInData 


Type/Description 
HDC Identifies the device context. 


WORD FAR * Points to an unsigned 16-bit integer that 
specifies whether duplex or simplex printing is used. It may 
be one of the following values: 
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Return Value 


Comments 


Parameter Type/Description 
Value Meaning 
0 Simplex 
1 Duplex with vertical binding 
2 Duplex with horizontal binding 


The return value specifies the outcome of the escape. It is 1 if the escape is successful. 
Otherwise, it is zero. 


An application should use the QUERYESCSUPPORT escape to determine whether an 
output device is capable of creating duplex output. If QUERYESCSUPPORT returns a 
nonzero value, the application should send the ENABLEDUPLEX escape even if simplex 
printing is desired. This guarantees replacement of any values set in the driver-specific 
dialog box. If duplex printing is enabled and an uneven number of NEXTFRAME 
escapes are sent to the driver prior to the ENDDOC escape, the driver will eject an addi- 
tional page before ending the print job. 


ENABLEPAIRKERNING 


Syntax 


short Escape(hDC, ENABLEPAIRKERNING, sizeof(int), /pNewKernFlag, 
IpOldKernF lag) 


This escape enables or disables the driver’s ability to kern character pairs automatically. 


_ Kerning is the process of adding or subtracting space between characters in a string of text. 


When pair kerning is enabled, the driver automatically kerns those pairs of characters that 
are listed in the font’s character-pair kerning table. The driver reflects this kerning both on 
the printer and in GetTextExtent function calls. 


Parameter Type/Description 
ADC HDC Identifies the device context. 
IpNewKernFlag LPINT Points to a short-integer value that specifies whether 


automatic pair kerning is to be enabled (1) or disabled (0). 


IpOldKernFlag LPINT Points to a short-integer value that will receive the 
previous automatic pair-kerning value. 
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ENABLERELATIVEWIDTHS 


Return Value 


Comments 


The return value specifies the outcome of the escape. It is 1 if the escape is successful; it is 
zero if the escape is not successful or not implemented. 


The default state of this escape is zero; automatic character-pair kerning is disabled. 


A driver does not have to support the ENABLEPAIRKERNING escape just because it 
supplies the character-pair kerning table to the application via the GETPAIRKERN- 
TABLE escape. In the case where the GETPAIRKERNTABLE escape is supported but 
the ENABLEPAIRKERNING escape is not, the application must properly space the 
kerned characters on the output device using the ExtTextOut function. 


ENABLERELATIVEWIDTHS 


Syntax 


Return Value 


Comments 


short Escape(hDC, ENABLERELATIVEWIDTHS, sizeof(int), /pDNewWidthF lag, 
lpOldWidthFlag) 


This escape enables or disables relative character widths. When relative widths are dis- 
abled (the default), each character’s width can be expressed as a number of device units. 
This guarantees that the extent of a string will equal the sum of the extents of the 
characters in the string. This allows applications to build an extent table by using one- 
character GetTextExtent function calls. 


When relative widths are enabled, the sum of a string may not equal the sum of the widths 
of the characters. Applications that enable this feature are expected to retrieve the font’s ex- 
tent table and compute relatively scaled string widths. 


Parameter Type/Description 
hDC HDC _ Identifies the device context. 


IpNewWidthF lag LPINT Points to a short-integer value that specifies whether 
relative widths are to be enabled (1) or disabled (0). 


lpOldWidthFlag LPINT Points to a short-integer value that will receive the 
previous relative character width value. 


The return value specifies the outcome of the escape. It is 1 if the escape is successful; it is 
zero if the escape is not successful or not implemented. 


The default state of this escape is zero; relative character widths are disabled. 


The values specified as font units and accepted and returned by the escapes described in 
this chapter are returned in the relative units of the font when the ENABLERELATIVE- 
WIDTHS escape is enabled. 
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It is assumed that only linear-scaling devices will be dealt with in a relative mode. Non- 
linear-scaling devices do not implement this escape. 


ENDDOC 
Syntax short Escape(hDC, ENDDOC, NULL, NULL, NULL) 


This escape ends a print job started by a STARTDOC escape. 


Parameter Type/Description 


hDC HDC _Identifies the device context. 


Return Value The return value specifies the outcome of the escape. It is positive if the escape is success- 
ful. Otherwise, it is negative. 


Comments If an application encounters a printing error or a canceled print operation, it must not at- 
tempt to terminate the operation by using the Escape function with either the ENDDOC 
or ABORTDOC escape. GDI automatically terminates the operation before returning the 
error value. 


If the application displays a dialog box to allow the user to cancel the print operation, it 
must send the ENDDOC escape before destroying the dialog box. 


The application must send the ENDDOC escape before freeing the procedure-instance 
address of the abort function, if any. 


END_PATH 
Syntax - short Escape(hDC, END_PATH, sizeof(PATH_INFO), /p/nData, NULL) 


This escape ends a path. A path is a connected sequence of primitives drawn in succession 
to form a single polyline or polygon. Paths enable applications to draw complex borders, 
filled shapes, and clipping areas by supplying a collection of other primitives defining the 
desired shape. 


Printer escapes supporting paths enable applications to render images on sophisticated dev- 
ices such as PostScript printers without generating huge polygons to simulate them. 
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END_PATH 


Return Value 


Comments 


To draw a path, an application first issues the BEGIN_PATH escape. It then draws the 
primitives defining the border of the desired shape and issues an END_PATH escape. 


The END_PATH escape takes as a parameter a pointer to a structure specifying the man- 
ner in which the path is to be rendered. The structure specifies whether or not the path is to 
be drawn and whether it is open or closed. Open paths define polylines, and closed paths 
define fillable polygons. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpInData PATH_INFO FAR * Points to a PATH_INFO data structure 


that defines how the path is to be rendered. See the following 
“Comments” section for more information on this data structure. 


The return value specifies the current path nesting level. If the escape is successful, the re- 
turn value is the number of BEGIN_PATH escape calls without a corresponding 
END_PATH call. Otherwise, the return value is —1. 


An application may begin a subpath within another path. If the subpath is closed, it is 
treated exactly like a polygon. If it is open, it is treated exactly like a polyline. 


An application may use the CLIP_TO_PATH escape to define a clipping area correspond- 
ing to the interior or exterior of the currently open path. 


The /pInData parameter points to a PATH_INFO data structure that specifies how to ren- 
der the path. This data structure has the following form: 


typedef struct { 


short RenderMode; 
BYTE FillMode; 
BYTE BkMode; 
LOGPEN Pen; 


LOGBRUSH Brush; 
DWORD BkColor; 
}PATH_INFO; 


END_PATH 
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The PATH_INFO structure has the following fields: 


Field 
RenderMode 


FillMode 


BkMode 


Pen 


Brush 


BkColor 


Description 


Specifies how the path is to be rendered. It may be one of the fol- 


lowing values: 


Value 
NO_DISPLAY (0) 
OPEN (1) 
CLOSED (2) 


Meaning 
The path is not drawn. 
The path is drawn as an open polygon. 


The path is drawn as a closed polygon. 


Specifies how the path is to be filled. It can be one of the follow- 


ing values: 


Value 


’ ALTERNATE (1) 


WINDING (2) 


Meaning 


The fill is done using the alternate fill 
algorithm. 


The fill is done using the winding fill 
algorithm. 


Specifies the background mode for filling the path. It can be one 


of the following values: 


Value 


OPAQUE 


TRANSPARENT 


Meaning 


The background is filled with the 
background color before the brush is 
drawn. 


The background is not changed. 


Specifies the pen with which the path is to be drawn. If Render- 
Mode is set to NO_DISPLAY, the pen is ignored. 


Specifies the brush with which the path is to be filled. If Render- 
Mode is set to NO_DISPLAY or OPEN, the brush is ignored. 


Specifies the color with which the path is filled if BkMode is set 


to OPAQUE. 
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ENUMPAPERBINS 
Syntax short Escape(hDC, ENUMPAPERBINS, sizeof(int), JpNumBins, lpOutData) 


Return Value 


Comments 


This escape retrieves attribute information about a specified number of paper bins. The 
GETSETPAPERBINS escape retrieves the number of bins available on a printer. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
lpNumBins LPINT Points to an integer that specifies the number of bins 


for which information is to be retrieved. 


IpOutData LPSTR Points to a data structure to which information about 
the paper bins is copied. The size of the structure depends on the 
number of bins for which information was requested. See the fol- 
lowing “Comments” section for a description of this data 
structure. 


The return value specifies the outcome of the escape. It is 1 if the escape is successful; it is 
zero if the escape is not successful or not implemented. 


The data structure to which the /pOutData parameter points consists of two arrays. The 
first is an array of short integers containing the paper-bin identifier numbers in the follow- 
ing format: 


short BinList[cBinMax] 


The number of integers in the array (cBinMax) is equal to the value pointed to by the 
IpNumBins parameter. . 


The second array in the data structure to which /pOutData points is an array of characters 
in the following format: 


char PaperNames{cBinMax]{cchBinName ] 


The cBinMax value is equal to the value pointed to by the IpNumBins parameter; the 
cchBinName value is the length of each string (currently 24). 


ENUMPAPERMETRICS | ai 


ENUMPAPERMETRICS 
Syntax short Escape(hDC, ENUMPAPERMETRICS, sizeof(int), /pMode, lpOutData) 


This escape performs one of two functions according to the mode: 


= It determines the number of paper types supported and returns this value, which can 
then be used to allocate an array of RECT data structures. 


= Itreturns one or more RECT data structures that define the areas on the page that can 
receive an image. 


Parameter Type/Description 

hDC HDC Identifies the device context. 

IpMode LPINT Points to an integer that specifies the mode for the 
escape. It can be one of the following values: 
Value Meaning 
0 The return value indicates how many 


RECT data structures are required to 
contain the information about the availa- 


ble paper types. 
1 The array of RECT structures to which 
IpOutData points is filled with the infor- 
mation. 
[pOutData LPRECT Points to an array of RECT data structures that re- 


turn all the areas that can receive an image. 


Return Value The return value is positive if successful, zero if the escape is not implemented, and nega- 
tive if an error occurred. 


EPSPRINTING 
Syntax short Escape(hDC, EPSPRINTING, sizeof(BOOL), /pBool, NULL) 


This escape suppresses the output of the Windows PostScript header control section, which 
is about 7K. If an application uses this escape, no GDI calls are allowed. 
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' Parameter Type/Description 
hDC HDC Identifies the device context. 
IpBool BOOL FAR * Points to a Boolean value indicating that 


downloading should be enabled (TRUE) or disabled (FALSE). 


Return Value The return value is positive if successful, zero if the escape is not implemented, and nega- 
tive if an error occurred. 


EXT_DEVICE_CAPS 
Syntax short Escape(hDC, EXT_DEVICE_CAPS, sizeof(int), [p/ndex, IpCaps) 


This escape retrieves information about device-specific capabilities. It supplements the 
GetDeviceCaps function. 


Parameter Type/Description 


hDC HDC Identifies the device context. 

IpIndex LPINT Points to a short integer specifying the index of the capabil- 
ity to be retrieved. It can be any one of the following values: 
Value Meaning — 
R2_CAPS (1) The /pCaps parameter indicates 


which of the 16 binary raster 
operations the device driver sup- 
ports. A bit will be set for each 
supported raster operation. For 
further information, see the 
description of the SetROP2 
function in Chapter 4, “Func- 
tions Directory,” in Reference, 
Volume I. 


EXT_DEVICE_CAPS 
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Parameter 


Type/Description 


Value 


PATTERN_CAPS (2) 


PATH_CAPS (3) 


POLYGON_CAPS (4) 


PATTERN_COLOR_CAPS (5) 


Meaning 


The /pCaps parameter returns 
the maximum dimensions of a 
pattern brush bitmap. The low- 
order word of the capability 
value contains the maximum 
width of a pattern brush bitmap, 
and the high-order word con- 
tains the maximum height. 


The /pCaps parameter indicates 
whether the device is capable of 
creating paths using alternate 
and winding interiors, and 
whether the device can do ex- 
clusive or inclusive clipping to 
path interiors. The path capabili- 
ties are obtained using the 
logical OR operation on the fol- 
lowing values: 


PATH_ALTERNATE (1) 
PATH_WINDING (2) 
PATH_INCLUSIVE (4) 
PATH_EXCLUSIVE (8) 


The /pCaps parameter returns 


’ the maximum number of poly- 


gon points supported by the 
device. The capability value is 
an unsigned value specifying 
the maximum number of points. 


The /pCaps parameter indicates 
whether the device can convert 
monochrome pattern bitmaps to 
color. The capability value is 1 
if the device can do pattern bit- 
map color conversions, and 
zero if it cannot. 
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Parameter Type/Description 
Value Meaning 
R2_TEXT_CAPS (6) The /pCaps parameter indicates 


whether the device is capable of 
performing binary raster opera- 
tions on text. The low-order 
word of the capability value 
specifies which raster opera- 
tions are supported for text. A 
bit is set for each supported 
raster operation, as in the 
R2_CAPS escape. The high- 
order word specifies the type of 
text to which the raster capabili- 
ties apply. It is obtained by 
applying the logical OR opera- 
tion to the following values 
together: 


RASTER_TEXT (1) 
DEVICE_TEXT (2) 
VECTOR_TEXT (4) 


IpCaps DWORD FAR * _ Points to a 32-bit integer to which the capabili- 
ties will be copied. 


Return Value The return value is nonzero if the specified extended capability is supported, and zero if it 
is not. 

EXTTEXTOUT 

Syntax short Escape(hDC, EXTTEXTOUT, sizeof(EXTTEXT_STRUCT), /pInData, NULL) 


This escape provides an efficient way for the application to call the GDI TextOut function 
when justification, letter spacing, and/or kerning are involved. 


This function is provided only for backward compatibility. New applications should use 
the GDI ExtTextOut function instead. 
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Return Value 


Comments 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpInData EXTTEXT_STRUCT FAR * Points to an EXTTEXT_STRUCT 


data structure that specifies the initial position, characters, and 
character widths of the string. See the following “Comments” section 
for more information on the EXTTEXT_STRUCT data structure. 


The return value specifies the outcome of the escape. It is 1 if the escape is successful; it is 
zero if the escape is not successful or not implemented. 


The EXTEXT_STRUCT data structure has the following format: 


typedef struct { 
WORD X; 
WORD. Y; 
WORD FAR *IpText; 
WORD FAR *lpWidths; 
} EXTTEXT_STRUCT; 


This structure has the following fields. 


Field Description 

X Specifies the x-coordinate of the upper-left corner of the string’s 
starting point. 

Y Specifies the y-coordinate of the upper-left corner of the string’s 
starting point. 

IpText Points to an array of cch character codes, where cch is the num- 
ber of bytes in the string (cch is also the number of words in the 
width array). 

IpWidths Points to an array of cch character widths to use when printing 


the string. The first character appears at (X,Y), the second at (X 
+ IpWidths[0],Y), the third at (X + IpWidths[0] + 
IpWidths[1],Y), and so on. These character widths are specified 
in the font units of the currently selected font. (The character 
widths will always be equal to device units unless the applica- 
tion has enabled relative character widths.) 


The units contained in the width array are specified as font units 
of the device. 
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FLUSHOUTPUT 
Syntax short Escape(hDC, FLUSHOUTPUT, NULL, NULL, NULL) 


This escape clears all output from the device’s buffer. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
Return Value The return value specifies the outcome of the escape. It is positive if the escape is success- 


ful. Otherwise, it is negative. 


GETCOLORTABLE 
Syntax short Escape(hDC, GETCOLORTABLE, sizeof(int), Jp/ndex, lpColor) 


This escape retrieves an RGB color-table entry and copies it to the location specified by 
the /pColor parameter. 


Parameter Type/Description 

hDC HDC Identifies the device context. 

IpIndex LPINT Points to a short-integer value that specifies the index 
of a color-table entry. Color-table indexes start at zero for the 
first table entry. 

IpColor DWORD FAR * Points to the long-integer value that will re- 


ceive the RGB color value for the given entry. 


Return Value The return value specifies the outcome of the escape. It is positive if the escape is success- 
ful. Otherwise, it is negative. 


GETEXTENDEDTEXTMETRICS 


Syntax short Escape(hDC, GETEXTENDEDTEXTMETRICS, sizeof(WORD), /pInData, 
IpOutData) 


This escape fills the buffer pointed to by the /pOutData parameter with the extended text 
metrics for the selected font. 
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Parameter Type/Description 

hDC HDC Identifies the device context. 

IpInData WORD FAR * Points to an unsigned 16-bit integer that speci- 
fies the number of bytes pointed to by the pOutData parameter. 

IpOutData EXTTEXTMETRIC FAR * Points to an EXTTEXT- 


METRIC data structure. See the following “Comments” section 
for a description of this data structure. 


Return Value The return value specifies the number of bytes copied to the buffer pointed to by the /pOut- 
Data parameter. This value will never exceed that specified in the nSize field pointed to by 
the /pInData parameter. The return value is zero if the escape fails or is not implemented. 


Comments The /pOutData parameter points to an EXTTEXTMETRIC data structure which has the 
following format: 


typedef struc{ 
Short etmSize; 
Short etmPointSize; 
short etmOrientation; 
short etmMasterHeight; 
short etmMinScale; 
short etmMaxScale; 
short .etmMasterUnits; 
short etmCapHeight; 
short etmXHeight; 
short etmLowerCaseAscent; 
short etmLowerCaseDescent; 
Short etmSlant; 
short. etmSuperScript; 
short etmSubScript; 
short etmSuperScriptSize; 
short etmSubScriptSize; 
short etmUnderlineOffset; 
short etmUnderlineWidth; 
short etmDoubleUpperUnderlineOffset; 
short etmDoubleLowerUnderlineOffset; 
short etmDoubleUpperUnder] ineWidth; 
short etmDoubleLowerUnderlineWidth; 
short etmStrikeOutOffset; 
short etmStrikeOutWidth; 
WORD etmKernPairs; 
WORD etmKernTracks; 
JEXTTEXTMETRIC; 


The EXTTEXTMETRIC data structure has the following fields: 
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Field 
etmSize 


etmPointSize 


etmOrientation 


etmMaster Height 


etmMinScale 


etmMaxScale 


Description 


Specifies the size of the structure in bytes. 


Specifies the nominal point size of this font 
in twips (twentieths of a point, or 1/1440 
inch). This is the intended size of the font; 
the actual size may differ slightly depending 
on the resolution of the device. 


Specifies the orientation of the font. The et- 
mOrientation field may be any of the 
following values: . 


Value Meaning 

0 Either orientation 
1 Portrait 

2 Landscape 


These values refer to the ability of this font 
to be placed on a page with the given orienta- 
tion. A portrait page has a height that is 
greater than its width. A landscape page has 

a width that is greater than its height. 


Specifies the font size in device units for 
which the values in this font’s extent table 
are exact. 


Specifies the minimum valid size for this 
font. The following equation illustrates how 
the minimum point size is determined: 


etmMinScale x 72 


smallest point size = 
P dfVertRes 


The value 72 represents the number of 
points per inch. The dfVertRes value is the 
number of dots per inch. 


Specifies the maximum valid size for this 
font. The following equation illustrates how 
the maximum point size is determined: 


etmMaxScale x 72 


largest point size = djVertRes 
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Field 


etmMasterUnits 


etmCapHeight 


etmXHeight 


etmLowerCaseAscent 


etmLowerCaseDescent 


etmSlant 


etmSuperScript 


etmSubScript 


etmSuperScriptSize 


Description 


The value 72 represents the number of 
points per inch. The dfVertRes value is the 
number of dots per inch. 


Specifies the integer number of units per em 
where an em equals etmMasterHeight. That 
is, etmMasterUnits is emtMaster Height 
expressed in font units rather than device 
units. 


Specifies the height in font units of upper- 
case characters in the font. Typically, this is 
the height of the capital H. 


Specifies the height in font units of lower- 
case characters in the font. Typically, this is 
the height of the lowercase x. 


Specifies the distance in font units that the 
ascender of lowercase letters extends above 
the baseline. Typically, this is the height of 
the lowercase d. 


Specifies the distance in font units that the 
descender of lowercase letters extends below 
the baseline. Typically, this is specified for 
the descender of the lowercase p. 


Specifies for an italicized or slanted font the 
angle of the slant measured in tenths of a 
degree clockwise from the upright version of 
the font. 


Specifies in font units the recommended 
amount to offset superscript characters from 
the baseline. This is typically a negative 
value. 


Specifies in font units the recommended 
amount to offset subscript characters from 
the baseline. This is typically a positive 
value. 


Specifies in font units the recommended size 
of superscript characters for this font. 
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Field 
etmSubScriptSize 


etmUnderlineOffset 


etmUnderlineWidth 


etmDoubleUpper UnderlineOffset 
etmDoubleLowerUnderlineOffset 


etmDoubleUpperUnderlineWidth 
etmDoubleLowerUnderline Width 


etmStrikeOutOffset 


etmStrikeOutWidth 


etmKernPairs 


etmKernTracks 
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Description 


Specifies in font units the recommended size 
of subscript characters for this font. 


Specifies in font units the offset downward 
from the baseline where the top of a single 
underline bar should appear. 


Specifies in font units the thickness of the 
underline bar. 


Specifies the offset in font units downward 
from the baseline where the top of the upper 
double underline bar should appear. 


Specifies the offset in font units downward 
from the baseline where the top of the lower 
double underline bar should appear. 


Specifies in font units the thickness of the 
upper underline bar. 


Specifies in font units the thickness of the 
lower underline bar. 


Specifies in font units the offset upward 
from the baseline where the top of a strike- 
out bar should appear. 


Specifies the thickness in font units of the 
strike-out bar. 


Specifies the number of character kerning 
pairs defined for this font. An application 
can use this value to calculate the size of the 
pair-kern table returned by the 
GETPAIRKERNTABLE escape. It will 
not be greater than 512 kern pairs. 


Specifies the number of kerning tracks de- 
fined for this font. An application can use 
this value to calculate the size of the track- 
kern table returned by the 
GETTRACKKERNTABLE escape. It will 
not be greater than 16 kern tracks. 
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The values returned in many of the fields of the EXTTEXTMETRIC structure are af- 
fected by whether relative character widths are enabled or disabled. For more information, 
see the description of ENABLERELATIVEWIDTHS escape earlier in this chapter. 
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Syntax 


Return Value 


Comments 


short Escape(hDC, GETEXTENTTABLE, sizeof(CHAR_RANGE STRUCT), 
lpInData, lpOutData) 


This escape retrieves the width (extent) of individual characters from a group of consecu- 
tive characters in the selected font’s character set. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpInData LPSTR Points toa CHAR_RANGE_ STRUCT data structure 


that defines the range of characters for which the width is to be re- 
trieved. See the following “Comments” section for more information 
on the CHAR_RANGE_STRUCT data structure. 


IpOutData LPINT Points to an array of short integers that receives the 
character widths. The size of the array must be at least (chLast — 
chFirst + 1). 


The return value specifies the outcome of the escape. It is 1 if the escape is successful, and 
zero if the escape is not successful. If the escape is not implemented, the return value is 
zero. 


The /pInData parameter points to a CHAR_RANGE_ STRUCT data structure that de- 
fines the range of characters for which the width is to be retrieved. The 
CHAR_RANGE STRUCT structure has the following format: 


typedef struct { 
BYTE chFirst; 
BYTE chLast; 

} CHAR_RANGE_STRUCT 
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This structure has the following fields: 


Field Description 


chFirst Specifies the character code of the first character whose width is 


to be retrieved. 


chLast Specifies the character code of the last character whose width is 
to be retrieved. 


The values retrieved are affected by whether relative character widths are enabled or dis- 


abled. For more information, see the ENABLERELATIVEWIDTHS escape, earlier in 
this chapter. 


GETFACENAME 
Syntax short Escape(hDC, GETFACENAME, NULL, NULL, /pFaceName) 


This escape retrieves the face name of the current physical font. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
lpFaceName LPSTR Points to a buffer of characters to receive the face 


name. This buffer must be at least 60 bytes in length. 


Return Value The return value is positive if the escape was successful, zero if the escape is not imple- 


mented, or negative if an error occurred. 


GETPAIRKERNTABLE 
Syntax short Escape(tDC, GETPAIRKERNTABLE, NULL, NULL, [pOutData) 


This escape fills the buffer pointed to by the /pOutData parameter with the character-pair 
kerning table for the selected font. 


GETPAIRKERNTABLE 12-28 


Return Value 


Comments 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpOutData KERNPAIR FAR * Points to an array of KERNPAIR data 


structures. This array must be large enough to accommodate the 
font’s entire character-pair kerning table. The number of 
character-kerning pairs in the font can be obtained from the 
EXTTEXTMETRIC data structure returned by the GETEX- 
TENDEDTEXTMETRICS escape. See the following 
“Comments” section for the format of the KERNPAIR data 
structure. 


The return value specifies the number of KERNPAIR structures copied to the buffer. This 
value is zero if the font does not have kerning pairs defined, the escape fails, or is not im- 
plemented. 


The KERNPAIR data structure has the following format: 


typedef struc { 


union { 
BYTE each [2]; /* UNION: ‘each’ and ‘both’ 
share the same memory */ 
WORD both; 
} kpPair; 
short kpKernAmount; 
} KERNPAIR; 


The KERNPAIR structure contains the following fields: 


Field Description 

kpPair.each[0] Specifies the character code for the first character in the kerning 
pair. . 

kpPair.each{1] Specifies the character code for the second character in the kern- 
ing pair. 

kpPair.both Specifies a WORD in which the first character in the kerning 


pair is in the low-order byte and the second character is in the 
high-order byte. 


kpKernAmount Specifies the signed amount that this pair will be kerned if they 
appear side by side in the same font and size. This value is typi- 
cally negative since pair-kerning usually results in two 
characters being set more tightly than normal. 
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The array of KERNPAIR structures is sorted in increasing order by the kpPair.both field. 


The values returned in the KERNPAIR structures are affected by whether relative 


character widths are enabled or disabled. For more information, see the description of the 
ENABLERELATIVEWIDTHS escape earlier in this chapter. 


GETPHYSPAGESIZE 
Syntax short Escape(hDC, GETPHYSPAGESIZE, NULL, NULL, /pDimensions) 


This escape retrieves the physical page size and copies it to the location pointed to by the 
IpDimensions parameter. 


Parameter Type/Description 
hDC HDC _ Identifies the device context. 


[pDimensions LPPOINT Points to a POINT data structure that will receive 
the physical page dimensions. The x field of the POINT data 
structure receives the horizontal size in device units, and the y 
field receives the vertical size in device units. 


Return Value The return value specifies the outcome of the escape. It is positive if the escape is success- 
ful. Otherwise, it is negative. 


GETPRINTINGOFFSET 
Syntax short Escape(4DC, GETPRINTINGOFFSET, NULL, NULL, /pOffset) 


This escape retrieves the offset from the upper-left corner of the physical page where the 
actual printing or drawing begins. This escape is generally not useful for devices that allow 
the user to set the origin of the printable area directly. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
lpOffset LPPOINT Points to a POINT structure that will receive the 


printing offset. The x field of the POINT structure receives the 
horizontal coordinate of the printing offset in device units, and 
the y field receives the vertical coordinate of the printing offset 
in device units. 
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Return Value The return value specifies the outcome of the escape. It is positive if the escape is success- 
ful. Otherwise, it is negative. 


GETSCALINGFACTOR 
Syntax short Escape(hDC, GETSCALINGFACTOR, NULL, NULL, /pFactors) 


This escape retrieves the scaling factors for the x- and y-axes of a printing device. For each 
scaling factor, the escape copies an exponent of 2 to the location pointed to by the IpFac- 
tors parameter. For example, the value 3 is copied to /pFactors if the scaling factor is 8. 


Scaling factors are used by printing devices that support graphics at a smaller resolution 
than text. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpFactors LPPOINT Points to the POINT data structure that will re- 


ceive the scaling factor. The x field of the POINT structure 
receives the scaling factor for the x-axis, and the y field receives 
the scaling factor for the y-axis. 


Return Value The return value specifies the outcome of the escape. It is positive if the escape is success- 
ful. Otherwise, it is negative. 


GETSETPAPERBINS 
Syntax short Escape(hDC, GETSETPAPERBINS, nCount, lpInData, lpOutData) 
This escape retrieves the number of paper bins available on a printer and sets the current 


paper bin. See the following “Comments” section for more information on the actions per- 
formed by this escape. 


Parameter Type/Description 

hDC HDC Identifies the device context. 

nCount int Specifies the number of bytes pointed to by the /pInData 
parameter. 

IpInData BinInfo FAR * Points to a BinInfo data structure that speci- 


fies the new paper bin. It may be set to NULL. 
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Parameter Type/Description 
[pOutData BinInfo FAR * Points to a BinInfo data structure that con- 
tains information about the current or previous paper bin and the 
number of bins available. 
Comments There are three possible actions for this escape, depending on the values passed in the /p/n- 


Data and IpOutData parameters: 


IpInData IpOutData Action 


NULL BinInfo Retrieves the number of bins and the number of the current bin. 


BinInfo BinInfo Sets the current bin to the number specified in the BinNumber field 
of the data structure to which /p/nData points and retrieves the num- 
ber of the previous bin. 


BinInfo NULL Sets the current bin to the number specified in the BinNumber field 
of the data structure to which /p/nData points. 


The BinInfo data structure has the following format: 


typedef struct{ 
DWORD BinNumber; 
DWORD NbrofBins; 


DWORD Reserved; 

DWORD Reserved; 

DWORD Reserved; 

DWORD Reserved; 
} BinInfo; 


The BinInfo structure has the following fields: 


Field Description - 
BinNumber Identifies the current or previous paper bin. 
NbrofBins Specifies the number of paper bins available. 


When setting a new bin, the setting does not take effect until a new device context is 
created (without initialization data). The setting will take immediate effect if the high bit of 
the bin number is set, so that the next page printed will come from the new bin. For ex- 
ample, 0x8001 uses the second bin immediately whenever 0x0001 sets the same bin as the 
default for later print jobs. 
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In general, only the immediate-selection form should be used by applications. Setting the 
bin for future print jobs is supported for backward compatibility to an earlier form of this 
escape which appeared in some versions of HP’s Page Control Language (PCL) and Post- 
Script. 


GETSETPAPERMETRICS 


Syntax 


Return Value 


short Escape(hDC, GETSETPAPERMETRICS, sizeof(RECT), [pNewPaper, 
lpPrevPaper) 


This escape sets the paper type according to the given paper metrics information. It also re- 
trieves the current printer’s paper metrics information. 


This escape expects a RECT data structure representing the imageable area of the physical 
page and assumes the origin is in the upper-left corner. 


Parameter Type/Description 
hDC HDC _ Identifies the device context. 
lpNewPaper LPRECT Points to a RECT data structure that defines the 


new imageable area. 


lpPrevPaper LPRECT Points to a RECT data structure that receives the 
previous imageable area. 


The return value is positive if successful, zero if the escape is not implemented, and nega- 
tive if an error occurs. 


Comments This escape is provided only for backward compatibility. New applications should use the 
GDI DeviceCapabilities and ExtDeviceMode functions instead. 

GETSETPAPERORIENT 

Syntax short Escape(hDC, GETSETPAPERORIENT, nCount, IpInData, NULL) 


This escape returns or sets the current paper orientation. 


Parameter Type/Description 


hDC HDC Identifies the device context. 
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Parameter Type/Description 

nCount Specifies the number of bytes pointed to by the /p/nData para- 
meter. 

lpInData ORIENT FAR * Points to an ORIENT data structure that 


specifies the new paper orientation. See the following “Com- 
ments” section for a description of this data structure. It may be 
set to NULL, in which case the GETSETPAPERORIENT 
escape returns the current paper orientation. 


Return Value The return value specifies the current orientation if /pInData is NULL; otherwise, it is the 
previous orientation. The return value is —1 if the escape failed. 


Comments This escape is provided only for backward compatibility. New applications should use the 
GDI DeviceCapabilities and ExtDeviceMode functions instead. 


The ORIENT data structure has the following format: 


typedef struct{ 
DWORD Orientation; 
DWORD Reserved; 
DWORD Reserved; 
DWORD Reserved; 
DWORD Reserved; 

} ORIENT; 


The Orientation field can be either of these values: 


Value Meaning 
l The new orientation is portrait. 
2 The new orientation is landscape. 


This escape is also known as GETSETPAPERORIENTATION. 


GETSETSCREENPARAMS 
Syntax short Escape(hDC, GETSETSCREENPARAMS, sizeof(SCREENPARAMS), 
IpInData, IpOutData) 


This escape retrieves or sets the current screen information for rendering halftones. 
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Return Value 


Comments 


Parameter Type/Description 

hDC HDC Identifies the device context. 

IpInData SCREENPARAMS FAR * | Points toa SCREENPARAMS 
data structure that contains the new screen information. This 
parameter may be NULL. 

lpOutData SCREENPARAMS FAR * | Points toa SCREENPARAMS 


data structure that retrieves the previous screen information. 
This parameter may be NULL. 


The return value specifies the outcome of the escape. It is positive if the escape is success- 
ful. Otherwise, it is negative. 


This escape affects how device-independent bitmaps (DIBs) are rendered and how color 
objects are filled. 


The SCREENPARAMS data structure has the following format: | 


typedef struct { 


int angle; 
int frequency; 
DWORD types; 

} SCREENPARAMS; 


The SCREENPARAMS structure has the following fields: 


Field Description 

angle Specifies in degrees the angle of the halftone screen. 
frequency Specifies in dots per inch of the screen frequency. 

types Is a mask containing bits which indicate the type of screen cell. 


If a pointer to this structure is passed as the /p/nData parameter, 
only one bit may be set. If the pOutData parameter contains a 
pointer to this structure, when the escape returns, the types field 
will have a bit set for each type supported by the printer driver. 
Acceptable bit values are: 


=» DIAMOND 
a DOT 
a ELLIPSE 
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a LINE 

GETTECHNOLOGY 

Syntax short Escape(hDC, GETTECHNOLOGY, NULL, NULL, /pTechnology) 


Return Value 


This escape retrieves the general technology type for a printer, thereby allowing an applica- 
tion to perform technology-specific actions. 


Parameter 
hDC 
IpTechnology 


Type/Description 
HDC Identifies the device context. 


LPSTR Points to a buffer to which the driver copies a null-ter- 
minated string containing the printer technology type, such as 
“PostScript.” 


The return value specifies the outcome of the escape. It is 1 if the escape is successful, and 
is zero if the escape is not successful or is not implemented. 


GETTRACKKERNTABLE 
short Escape(hDC, GETTRACKKERNTABLE, NULL, NULL, /pOutData) 


Syntax 


This escape fills the buffer pointed to by the pOutData parameter with the track-kerning 
table for the currently selected font. 


Parameter 
hDC 
[pOutdata 


Type/Description 
HDC _ Identifies the device context. 


KERNTRACK FAR * Points to an array of KERNTRACK 
structures. This array must be large enough to accommodate all 
the font’s kerning tracks. The number of tracks in the font can be 
obtained from the EXTTEXTMETRIC structure returned by 
the GETEXTENDEDTEXTMETRICS escape. See the follow- 
ing “Comments” section for the format of the KERNTRACK 
data structure. 
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Return Value The return value specifies the number of KERNTRACK structures copied to the buffer. 
This value is zero if the font does not have kerning tracks defined, or if the escape fails or 
is not implemented. 


Comments The KERNTRACK data structure has the following format: 
typedef struct { 
short ktDegree; 
short ktMinSize; 
short ktMinAmount; 
short ktMaxSize; 
short ktMaxAmount; 
} KERNTRACK; 


The KERNTRACK structure contains the following fields: 


Field - Description 


ktDegree Specifies the amount of track kerning. Increasingly negative 
values represent tighter track kerning, and increasingly positive 
values represent looser track kerning. 


ktMinSize Specifies in device units the minimum font size for which linear 
track kerning applies. 


ktMinAmount Specifies in font units the amount of track kerning to apply to 
font sizes less than or equal to the size specified by the ktMin- 
Size field. 


ktMaxSize | Specifies in device units the maximum font size for which linear 
track kerning applies. 


ktMaxAmount Specifies in font units the amount of track kerning to apply to 
font sizes greater than or equal to the size specified by the 
ktMaxSize field. 


Between the ktMinSize and ktMaxSize font sizes, track keming is a linear function from 
ktMinAmount to ktMaxAmount. The values returned in the KERNTRACK structures 
are affected by whether relative character widths are enabled or disabled. For more infor- 
mation, see the description of the ENABLERELATIVEWIDTHS escape earlier in this 
chapter. 
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GETVECTORBRUSHSIZE 


Syntax short Escape(hDC, GETVECTORBRUSHSIZE, sizeof(LOGBRUSH), /pInData, 
lpOutData) 


This escape retrieves in device units the size of a plotter pen used to fill closed figures. 


GDI uses this information to prevent the plotter pen from writing over the borders of the 
figure when filling closed figures. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpInData LOGBRUSH FAR * Points toa LOGBRUSH data structure 


that specifies the brush for which data are to be returned. 


IpOutData LPPOINT Points to a POINT data structure that contains in 
its second word the width of the pen in device units. 


Return Value The return value specifies the outcome of the escape. It is 1 if the escape is successful; it is 
zero if the escape is not successful or is not implemented. 


GETVECTORPENSIZE 
Syntax short Escape(hDC, GETVECTORPENSIZE, sizeof(LOGPEN), /p/nData, 
lpOutData) 


This escape retrieves the size in device units of a plotter pen. GDI uses this information to 
prevent hatched brush patterns from overwriting the border of a closed figure. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpInData LOGPEN FAR * Points toa LOGPEN data structure that 


specifies the pen for which the width is to be retrieved. 


[pOutData LPPOINT Points to a POINT data structure that contains in 
its second word the width of the pen in device units. 


Return Value The return value specifies the outcome of the escape. It is 1 if the escape is successful; it is 
zero if the escape is not successful or if it is not implemented. 
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MFCOMMENT 
Syntax BOOL Escape(hDC, MFCOMMENT, nCount, IpComment, NULL) 
This escape adds a comment to a metafile. 
Parameter Type/Description 
hDC HDC Identifies the device context for the device on which the 
metafile appears. 
nCount short Specifies the number of characters in the string pointed 
to by the Jp>Comment parameter. 
IpComment LPSTR Points to a null-terminated string that contains the 
comment that will appear in the metafile. 
Return Value The return value specifies the outcome of the escape. It is —1 if an error such as insufficient 


memory or an invalid port specification occurs. Otherwise, it is positive. 


NEWFRAME 

Syntax short Escape(hDC, NEWFRAME, NULL, NULL, NULL) 
This escape informs the device that the application has finished writing to a page. This 
escape is typically used with a printer to direct the device driver to advance to a new page. 
Parameter Type/Description 
hDC HDC Identifies the device context. 

Return Value The return value specifies the outcome of the escape. It is positive if the escape is success- 


ful. Otherwise, it is one of the following values: 


Value Meaning 


SP_APPABORT Job was terminated because the application’s abort func- 
tion returned zero. 


SP_ERROR General error. 
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NEXTBAND 


Comments 


NEXTBAND 
Syntax 


Return Value 


Value Meaning 


SP_OUTOFDISK Not enough disk space is currently available for spool- 
ing, and no more space will become available. 


SP_OUTOFMEMORY Not enough memory is available for spooling. 
SP_USERABORT User terminated the job through the Print Manager. 


Do not use the NEXTBAND escape with NEWFRAME. For banding drivers, GDI re- 
plays a metafile to the printer, simulating a sequence of NEXTBAND escapes. 


The NEWFRAME escape restores the default values of the device context. Consequently, 
if a font other than the default font is selected when the application calls the NEW- 
FRAME escape, the application must select the font again following the NEWFRAME 
escape. 


short Escape(hDC, NEXTBAND, NULL, NULL, [pBandRect) 


This escape informs the device driver that the application has finished writing to a band, 
causing the device driver to send the band to the Print Manager and return the coordinates 
of the next band. Applications that process banding themselves use this escape. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpBandRect LPRECT Points to the RECT data structure that will receive 


the next band coordinates. The device driver copies the device 
coordinates of the next band into this structure. 


The return value specifies the outcome of the escape. It is positive if the escape is success- 
ful. Otherwise, it is one of the following values: 


Value Meaning 


SP_APPABORT Job was terminated because the application’s abort func- 
tion returned zero. 


SP_ERROR General error. 
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Comments 


Value Meaning 

SP_OUTOFDISK _ Not enough disk space is currently available for spool- 
ing, and no more space will become available. 

SP_OUTOFMEMORY Not enough memory is available for spooling. 

SP_USERABORT User terminated the job through the Print Manager. 


The NEXTBAND escape sets the band rectangle to the empty rectangle when printing 
reaches the end of a page. 


Do not use the NEWFRAME escape with NEXTBAND. 


PASSTHROUGH 


Syntax 


Return Value 


Comments 


short Escape(hDC, PASSTHROUGH, nCount, IpInData, NULL) 


This escape allows the application to send data directly to the printer, bypassing the stand- 
ard print-driver code. 


NOTE To use this escape, an application must have thorough knowledge of how the particular printer 
operates. 


Parameter Type/Description 

hDC HDC Identifies the device context. 

nCount short Specifies the number of bytes to which the /pInData 
parameter points, 

lpInData LPSTR Points to a structure whose first word (16 bits) con- 


tains the number of bytes of input data. The remaining bytes of 
the structure contain the data itself. 


The return value specifies the number of bytes transferred to the printer if the escape is 
successful. It is less than zero if the escape is not implemented, and less than or equal to 
zero if the escape is not successful. 


There may be restrictions on the kinds of device data an application can send to the device 
without interfering with the operation of the driver. In general, applications must avoid re- 
setting the printer or causing the page to be printed. . 
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It is strongly recommended that applications not perform functions that consume printer 
memory, such as downloading a font or a macro. 


An application can avoid corrupting its data stream when issuing multiple, consecutive 
PASSTHROUGH escapes if it does not access the printer any other way during the 


sequence. 
QUERYESCSUPPORT 
Syntax short Escape(hDC, QUERYESCSUPPORT, sizeof(int), /pEscNum, NULL) 


This escape determines whether a particular escape is implemented by the device driver. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpEscNum LPINT Points to a short-integer value that specifies the 


escape function to be checked. 


Return Value The return value specifies whether a particular escape is implemented. It is nonzero for im- 
plemented escape functions. Otherwise, it is zero. 


If the JpEscNum parameter is set to DRAWPATTERNRECT, the return value is one of the 


following: 

Value Meaning 

0 DRAWPATTERNRECT is not implemented. 

1 DRAWPATTERNRECT is implemented for a printer other than 

the HP LaserJet IIP; this printer supports white rules. 

2 DRAWPATTERNRECT is implemented for the HP LaserJet IIP. 
RESTORE_CTM 
Syntax short Escape(hDC, RESTORE_CTM, NULL, NULL, NULL) 


This escape restores the previously saved current transformation matrix. 


The current transformation matrix controls the manner in which coordinates are translated, 
rotated, and scaled by the device. By using matrices, an application can combine these 
operations in any order to produce the desired mapping for a particular picture. 
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Parameter Type/Description 
hDC HDC Identifies the device context. 
Return Value The return value specifies the number of SAVE_CTM escape calls without a correspond- 


ing RESTORE_CTM call. If the escape is unsuccessful, the return value is —1. 


Comments Applications should not make any assumptions about the initial contents of the current 
transformation matrix. 


This escape uses a matrix specification based on the Microsoft OS/2 Presentation Manager 
graphics programming interface (GPI) model, which: is an integer-coordinate system simi- 
lar to the system which GDI uses. 


SAVE_CTM 
Syntax short Escape(h4DC, SAVE_CTM, NULL, NULL, NULL) 
This escape saves the current transformation matrix. 


The current transformation matrix controls the manner in which coordinates are translated, 
rotated, and scaled by the device. By using matrices, an application can combine these 
operations in any order to produce the desired mapping for a particular picture. 


An application can restore the matrix by using the RESTORE_CTM escape. 


An application typically saves the current transformation matrix before changing it. This al- 
lows the application to restore the previous state upon completion of a particular operation. 


Parameter Type/Description 


hDC HDC Identifies the device context. 


Return Value The return value specifies the number of SAVE_CTM escape calls without a correspond- 
ing RESTORE_CTM call. The return value is zero if the escape was unsuccessful. 


Comments Applications should not make any assumptions about the initial contents of the current 
transformation matrix. 


Applications are expected to restore the contents of the current transformation matrix. 


This escape uses a matrix specification based on the OS/2 Presentation Manager graphics 
programming interface (GPI) model, which is an integer-coordinate system similar to the 
system that GDI uses. 
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SELECTPAPERSOURCE 


This escape has been superseded by the GETSETPAPERBINS escape and is provided 
only for backward compatibility. New applications should use the GETSETPAPERBINS 
escape instead. 


SETABORTPROC 
Syntax short Escape(hDC, SETABORTPROC, NULL, /pAbortFunc, NULL) 
This escape sets the abort function for the print job. 


If an application is to allow the print job to be canceled during spooling, it must set the 
abort function before the print job is started with the STARTDOC escape. Print Manager 
calls the abort function during spooling to allow the application to cancel the print job or 
to process out-of-disk-space conditions. If no abort function is set, the print job will fail if 
there is not enough disk space for spooling. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
[pAbortFunc FARPROC Points to the application-supplied abort function. 


See the following “Comments” section for details. 


Return Value The return value specifies the outcome of the escape. It is positive if the escape is success- 
ful. Otherwise, it is negative. 


Comments The address passed as the IpAbortFunc parameter must be created by using the Make- 
ProcInstance function. 


The callback function must use the Pascal calling convention and must be declared FAR. 
The abort function must have the following form: 


Callback Function short FAR PASCAL AbortFunc(hPr, code) 
HDC hPr; 
short code; 


AbortFunc is a placeholder for the application-supplied function name. The actual name 
must be exported by including it in an EXPORTS statement in the application’s module- 
definition file. 
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Parameter Description 
hPr Identifies the device context. 
code Specifies whether an error has occurred. It is zero if no error has 


occurred. It is SP_OUTOFDISK if Print Manager is currently 
out of disk space and more disk space will become available if 
the application waits. 


If code is SP_LOUTOFDISK, the application does not have to 
abort the print job. If it does not, it must yield to Print Manager 
by calling the PeekMessage or GetMessage function. 


Return Value 


The return value should be nonzero if the print job is to continue, and zero if it is canceled. 


SETALLJUSTVALUES 
Syntax short Escape(hDC, SETALLJUSTVALUES, sizeof(JUST_VALUE_STRUCT), 
IpInData, NULL) 


This escape sets all of the text-justification values that are used for text output. 


Text justification is the process of inserting extra pixels among break characters in a line of 
text. The blank character is normally used as a break character. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpInData JUST_VALUE_ STRUCT FAR * Points toa 


JUST_VALUE_STRUCT data structure that defines the text- 
justification values. See the following “Comments” section for 
more information on the JUST_VALUE STRUCT data struc- 


ture. 

Return Value The return value specifies the outcome of the escape. It is 1 if the escape is successful. 
Otherwise, it is zero. 

Comments The /pInData parameter points to a JUST_VALUE_STRUCT data structure that de- 


scribes the text-justification values used for text output. The JUST_VALUE_STRUCT 
structure has the following format: 
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typedef struct { 
short nCharExtra; 
WORD nCharCount; 
short nBreakExtra; 
WORD nBreakCount ; 
} JUST_VALUE_STRUCT; 


This structure has the following fields: 


Field Description 

nCharExtra Specifies the total extra space (in font units) that must be dis- 
tributed over nCharCount characters. 

nCharCount Specifies the number of characters over which nCharExtra is 
distributed. 

nBreakExtra Specifies the total extra space (in font units) that is distributed 
over nBreakCount characters. 

nBreakCount Specifies the number of break characters over which nBreak- 
Extra is distributed. 


The units used for nCharExtra and nBreakExtra are the font units of the device and are 
dependent on whether relative character widths were enabled with the ENABLE- 
RELATIVEWIDTHS escape. 


The values set with this escape apply to subsequent calls to the TextOut function. The 
driver stops distributing the extra space specified in the nCharExtra field when it has out- 
put the number of characters specified in the nCharCount field. Likewise, it stops dis- 
tributing the space specified by the nBreakExtra field when it has output the number of 
characters specified by the nBreakCount field. A call on the same string to the GetText- 
Extent function made immediately after the call to the TextOut function will be processed 
in the same manner. 


To re-enable justification with the SetTextJustification and SetTextCharacterExtra func- 
tions, an application should call the SETALLJUSTVALUES escape and set the nChar- 
Extra and nBreakExtra fields to zero. 


SET_ARC_DIRECTION 
Syntax short Escape(i4DC, SET_ARC_DIRECTION, sizeof(int), /pDirection, NULL) 


This escape specifies the direction in which elliptical arcs are drawn using the GDI Arc 
function. | 
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By convention, elliptical arcs are drawn counterclockwise by GDI. This escape lets an 
application draw paths containing arcs drawn clockwise. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpDirection LPINT Points to a short integer specifying the arc direction. It 


can be either of the following values: 
as COUNTERCLOCKWISE (0) 
a CLOCKWISE (1) 


Return Value The return value is the previous arc direction. 
Comments This escape maps to PostScript language elements and is intended for PostScript line dev- 
ices. 


SET_BACKGROUND_COLOR 


Syntax short Escape(hDC, SET BACKGROUND_COLOR, nCount, IpNewColor, 
IpOldColor) 


This escape sets and retrieves the current background color for the device. 


The background color is the color of the display surface before an application draws any- 
thing on the device. This escape is particularly useful for color printers and film recorders. 


This escape should be sent before the application draws anything on the current page. 


Parameter Type/Description 

hDC HDC Identifies the device context. 

nCount int Specifies the number of bytes pointed to by the jpNew- 
Color parameter. 

lpNewColor DWORD FAR * Points to a 32-bit integer specifying the 


desired background color. This parameter can be NULL if the 
application is merely retrieving the current background color. 


[pOldColor DWORD FAR * Points to a 32-bit integer which receives the 
previous background color. This parameter can be NULL if the 
application does not use the previous background color. 
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SET_BOUNDS 


Return Value 


Comments 


SET_BOUNDS 
Syntax 


Return Value 


Comments 


The return value is TRUE if the escape was successful and FALSE if it was unsuccessful. 


The default background color is white. 


The background color is reset to the default when the device driver receives an ENDDOC 
or ABORTDOC escape. 


short Escape(i4DC, SET_BOUNDS, sizeof(RECT), /p/nData, NULL) 


This escape sets the bounding rectangle for the picture being produced by the device driver 
supporting the given device context. It is used when creating images in a file format such 
as Encapsulated PostScript (EPS) and Hewlett-Packard Graphics Language eo for 
which there is a device driver. 


Parameter Type/Description 

hDC HDC Identifies the device context. 

IpInData LPRECT Points to a RECT data structure that specifies in 
device coordinates a rectangle that bounds the image to be out- 
put. 


The return value is TRUE if the escape was successful; otherwise, the return value is 
FALSE. 


An application should issue this escape before each page in the image. For single-page im- 
ages, this escape should be issued immediately before the STARTDOC escape. 


When an application uses coordinate-transformation escapes, device drivers may not per- 
form bounding box calculations correctly. When an application uses the SET_BOUNDS 
escape, the driver does not have to calculate the bounding box. 


Applications should always use this escape to ensure support for the Encapsulated Post- 
Script (EPS) printing capabilities that will be built into future PostScript drivers. 
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SETCOLORTABLE 


Syntax 


Return Value 


Comments 


short Escape(i4DC, SETCOLORTABLE, sizeof(COLORTABLE_STRUCT), 
IpInData, lpColor) 


This escape sets an RGB color-table entry. If the device cannot supply the exact color, the 
function sets the entry to the closest possible approximation of the color. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpInData COLORTABLE_STRUCT FAR * Points toa 


COLORTABLE_STRUCT data structure that contains the 
index and RGB value of the color-table entry. See the following 
“Comments” section for more information on the 
COLORTABLE_STRUCT data structure. 


lpColor DWORD FAR * | Points to the long-integer value that is to re- 
ceive the RGB color value selected by the device driver to 
represent the requested color value. 


The return value specifies the outcome of the escape. It is positive if the escape is success- 
ful. Otherwise, it is negative. 


The COLORTABLE_STRUCT data structure has the following format: 
typedef struct { 

WORD = Index; 

DWORD rgb; 
} COLORTABLE_STRUCT ; 


This structure has the following fields: 


Field Description 

Index Specifies the color-table index. Color-table entries start at zero 
for the first entry. 

rgb Specifies the desired RGB color value. 


A device’s color table is a shared resource; changing the system display color for one 
window changes it for all windows. Only applications developers who have a thorough 
knowledge of the display driver should use this escape. 


The SETCOLORTABLE escape has no effect on devices with fixed color tables. 
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SETCOPYCOUNT 


This escape is intended for use by both printer and display drivers. However, the EGA and 
VGA color drivers do not support it. 


This escape changes the palette used by the display driver. However, since the driver’s 
color-mapping algorithms will probably no longer work with a different palette, an exten- 
sion has been added to this function. 


If the color index pointed to by the /pInData parameter is OXFFFF, the driver is to leave all 
color-mapping functionality to the calling application. The application must use the proper 
color-mapping algorithm and take responsibility for passing the correctly mapped physical 
color to the driver (instead of the logical RGB color) in such device-driver functions as 
RealizeObject and ColorInfo. 


For example, if the device supports 256 colors with palette indexes of 0 through 255, the 
application would determine which index contains the color that it wants to use in a certain 
brush. It would then pass this index in the low-order byte of the DWORD logical color 
passed to the RealizeObject device-driver function. The driver would then use this color 
exactly as passed instead of performing its usual color-mapping algorithm. If the applica- 
tion wants to reactivate the driver’s color-mapping algorithm (that is, if it restores the origi- 
nal palette when switching from its window context), then the color index pointed to by 
IpInData should be OxFFFE. 


SETCOPYCOUNT 


Syntax 


Return Value 


short Escape(hDC, SETCOPYCOUNT, sizeof(int), IpNumCopies, lpActualCopies) 


This escape specifies the number of uncollated copies of each page that the printer is to 
print. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpNumCopies LPINT Points toa short-integer value that contains the num- 


ber of uncollated copies to be printed. 


IpActualCopies LPINT Points to a short-integer value that will receive the 
number of copies to be printed. This may be less than the num- 
ber requested if the requested number is greater than the device’s 
maximum copy count. 


The return value specifies the outcome of the escape. It is 1 if the escape is successful; it is 
zero if the escape is not successful. If the escape is not implemented, the return value is 


~ Zero. 
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SETKERNTRACK 


Syntax 


Return Value 


Comments 


short Escape(hDC, SETKERNTRACK, sizeof(int), lpNewTrack, lpOldTrack) 


This escape specifies which kerning track to use for drivers that support automatic track 
kerning. A kerning track of zero disables automatic track kerning. 


When track kerning is enabled, the driver will automatically kern all characters according 
to the specified track. The driver will reflect this kerning both on the printer and in Get- 
TextExtent function calls. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
IpNewTrack LPINT Points to a short-integer value that specifies the kern- 


ing track to use. A value of zero disables this feature. Values in 
the range 1 to nKernTracks correspond to positions in the track- 
kerning table (using 1 as the first item in the table). For more 
information, see the description of the EXTTEXTMETRIC 
structure provided under the description of the GETEXTEN- 
DEDTEXTMETRICS escape. 


[pOldTrack LPINT Points to a short-integer value that will receive the 
previous kerning track. 


The return value specifies the outcome of the escape. It is 1 if the escape is successful; it is 
zero if the escape is not successful or not implemented. 


Automatic track kerning is disabled by default. 


A driver does not have to support the ENABLEPAIRKERNING escape just because it 
supplies the track-kerning table to the application by using the GETTRACKKERN- 
TABLE escape. In the case where GETTRACKKERNTABLE is supported but the SET- 
KERNTRACK escape is not, the application must properly space the characters on the 
output device. 
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SETLINECAP 
Syntax short Escape(ihDC, SETLINECAP, sizeof(int), /pNewCap, IpOldCap) 

This escape sets the line end cap. 

A line end cap is that portion of a line segment that appears on either end of the segment. 

The cap may be square or circular. It can extend past, or remain flush with the specified 

segment end points. 

Parameter Type/Description 

hDC HDC Identifies the device context. 

IpNewCap LPINT Points to a short-integer value that specifies the end-cap 
type. The possible values and their meanings are given in the follow- 
ing list: 

Value Meaning 

-l Line segments are drawn by using the default GDI 
end cap. 

0 Line segments are drawn with a squared end point 
that does not project past the specified segment 
length. 

1 Line segments are drawn with a rounded end 
point; the diameter of this semicircular arc is equal 
to the line width. 

2 Line segments are drawn with a squared end point 
that projects past the specified segment length. 
The projection is equal to half the line width. 

IpOldCap LPINT Points to a short-integer value that specifies the previous 
end-cap setting. 

Return Value The return value specifies the outcome of the escape. It is positive if the escape is success- 
ful. Otherwise, it is negative. 
Comments The interpretation of this escape varies with page-description languages (PDLs). Consult 


the PDL documentation for its exact meaning. 


This escape is also known as SETENDCAP. 


SETLINEJOIN 
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SETLINEJOIN 
Syntax 


Return Value 


Comments 


short Escape(hDC, SETLINEJOIN, sizeof(int), jpNewJoin, lpOldJoin) 


This escape specifies how a device driver will join two intersecting line segments. The 
intersection can form a rounded, squared, or mitered corner. 


Parameter 


hDC 
IpNewJoin 


IpOldJoin 


Type/Description 


HDC 


Identifies the device context. 


LPINT Points to a short-integer value that specifies the type of 
intersection. The possible values and their meanings are given in the 


following list: 


Value 


—1 


Meaning 


Line segments are joined by using the default GDI 
setting. 


Line segments are joined with a mitered corner; 
the outer edges of the lines extend until they meet 
at an angle. This is referred to as a miter join. 


Line segments are joined with a rounded corner; a 
semicircular arc with a diameter equal to the line 
width is drawn around the point where the lines 
meet. This is referred to as a round join. 


Line segments are joined with a squared end point; 
the outer edges of the lines are not extended. This 
is referred to as a bevel join. 


LPINT Points to a short-integer value that specifies the previous 


line join setting. 


The return value specifies the outcome of the escape. It is positive if the escape is success- 


ful. Otherwise, it is negative. 


The interpretation of this escape varies with page-description languages (PDLs). Consult 
the PDL documentation for its exact meaning. 


If an application specifies a miter join but the angle of intersection is too small, the device 
driver ignores the miter setting and uses a bevel join instead. 


SETMITERLIMIT 
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SETMITERLIMIT 
Syntax short Escape(hDC, SETMITERLIMIT, sizeof(int), IpNewMiter, lpOldMiter) 


Return Value 


Comments 


This escape sets the miter limit for a device. The miter limit controls the angle at which a 
device driver replaces a miter join with a bevel join. 


Parameter Type/Description 

hDC HDC Identifies the device context. 

nCount short Specifies the number of bytes to which the JpNewMiter 
parameter points. 

IpNewMiter LPINT Points to a short-integer value that specifies the 


desired miter limit. Only values greater than or equal to —1 are 
valid. If this value is —1, the driver will use the default GDI 
miter limit. 


IpOldMiter LPINT Points to a short-integer value that specifies the pre- 
vious miter-limit setting. 


The return value specifies the outcome of the escape. It is positive if the escape is success- 
ful. Otherwise, it is negative. 


The miter limit is defined as follows: 


miter length _ 1 
line width ~ sin (x/2) 


X is the angle of the line join in radians. 


The interpretation of this escape varies with page-description languages (PDLs). Consult, 
the PDL documentation for its exact meaning. 


SET_POLY_MODE 


Syntax 


short Escape(iDC, SET_POLY_MODE, sizeof(int), pMode, NULL) 


This escape sets the poly mode for the device driver. The poly mode is a state variable indi- 
cating how to interpret calls to the GDI Polygon and Polyline functions. 


The SET_POLY_MODE escape enables a device driver to draw shapes (such as Bezier 
curves) not supported directly by GDI. This permits applications that draw complex curves 
to send the curve description directly to a device without having to simulate the curve as a 
polygon with a large number of points. 


SET_POLY_MODE 
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Parameter 


hDC 
IpMode 


Type/Description 
HDC _Identifies the device context. 


LPINT Points to a short integer specifying the desired poly 
mode. The poly mode is a state variable indicating how points in 
Polygon or Polyline function calls should be interpreted. All 
device drivers are not required to support all possible modes. A 
device driver returns zero if it does not support the specified 
mode. The /pMode parameter may be one of the following values: 


Value Meaning 

PM_POLYLINE (1) The points define a conventional poly- 
gon or polyline. 

PM_BEZIER (2) The points define a sequence of 4- 


point Bezier spline curves. The first 
curve passes through the first four 
points, with the first and fourth points 
as end points, and the second and third 
points as control points. Each sub- 
sequent curve in the sequence has the 
end point of the previous curve as its 
start point, the next two points as con- 
trol points, and the third as its end 
point. 


The last curve in the sequence is per- 
mitted to have fewer than four points. 
If the curve has only one point, it is 
considered a point. If it has two 
points, it is a line segment. If it has 
three points, it is a parabola defined 
by drawing a Bezier curve with the 
first and third points as end points and 
the two control points equal to the sec- 


ond point. 
PM_POLYLINE- The points specify a list of coordinate 
SEGMENT (3) pairs. Line segments are drawn con- 


necting each successive pair of points. 
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SET_SCREEN_ANGLE 


Return Value 


Comments 


The return value is the previous poly mode. If the return value is zero, the device driver 
did not handle the request. 


An application should issue the SET_POLY MODE escape before it draws a complex 
curve. It should then call the Polyline or Polygon function with the desired control points 
defining the curve. After drawing the curve, the application should reset the driver to its 
previous state by issuing the SET. POLY MODE escape. 


Polyline calls draw using the currently selected pen. 


Polygon calls draw using the currently selected pen and brush. If the start and end points 
are not equal, a line is drawn from the start point to the end point before filling the polygon 
(or curve). 


GDI treats Polygon calls using PM_POLYLINESEGMENT mode exactly the same as 
Polyline calls. 


Four points define a Bezier curve. GDI generates the curve by connecting the first and sec- 
ond, second and third, and third and fourth points. GDI then connects the midpoints of 
these consecutive line segments. Finally, GDI connects the midpoints of the lines connect- 
ing the midpoints, and so forth. 


The line segments drawn in this way converge to a curve defined by the following para- 
metric equations, expressed as a function of the independent variable t. 


X(0) = (1-1)°x1 + 3(1-1)7tx2 + 31-173 + Px 
Y(t) = (1-1)? y1 + 31-1092 + 3(1-DPy3 + Pya 


The points (x1,y1), (x2,y2), (x3,y3) and (x4,y4) are the control points defining the curve. 
The independent variable ¢ varies from 0 to 1. 


Primitive types other than PM_BEZIER and PM_POLYLINESEGMENT may be added to 
this escape in the future. Applications should check the return value from this escape to de- 
termine whether or not the driver supports the specified poly mode. 


_ SET_SCREEN_ANGLE 


Syntax 


short Escape(hDC, SET SCREEN_ANGLE, sizeof(int), jpAngle, NULL) 


This escape sets the current screen angle to the desired angle and enables an application to 
simulate the tilting of a photographic mask in producing a color separation for a particular 
primary. 


SET SPREAD oo er 


Return Value 


Comments 


SET_SPREAD 
Syntax 


Parameter Type/Description 

hDC HDC Identifies the device context. 

IpAngle | LPINT Points to a short-integer value specifying the desired 
screen angle in tenths of a degree. The angle is measured coun- 
terclockwise. 


The return value is the previous screen angle. 


Four-color process separation is the process of separating the colors comprising an image 
into four component primaries: cyan, magenta, yellow, and black. The image is then repro- 
duced by overprinting each primary. 


In traditional four-color process printing, half-tone images for each of the four primaries 
are photographed against a mask tilted to a particular angle. Tilting the mask in this man- 
ner minimizes unwanted moire patterns caused by overprinting two or more colors. 


The device driver defines the default screen angle. 


short Escape(hDC, SET_SPREAD, sizeof(int), [pSpread, NULL) 


This function sets the amount that nonwhite primitives are expanded for a given device to 
provide a slight overlap between primitives to compensate for imperfections in the repro- 
duction process. 


Spot color separation is the process of separating an image into each distinct color used in 
the image. The image is reproduced by overprinting each successive color in the image. 


When reproducing a spot-separated image, the printing equipment must be calibrated to 
align each page exactly on each pass. However, differences in temperature, humidity, and 
so forth, between passes often cause images to align imperfectly on subsequent passes. For 
this reason, lines in spot separations are often widened (spread) slightly to make up for 
problems in registering subsequent passes through the printer. This process is called trap- 
ping. The SET_SPREAD escape implements this process. 


Parameter * Type/Description 
hDC HDC Identifies the device context. 
lpSpread LPINT Points to a short-integer value that specifies the 


amount, in pixels, by which all nonwhite primitives are to be ex- 
panded. 
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STARTDOC 


Return Value 


Comments 


STARTDOC 
Syntax 


Return Value 


Comments 


The return value is the previous spread value. 


The default spread is zero. 


The current spread applies to all bordered primitives (whether or not the border is visible) 
and text. 


short Escape(hDC, STARTDOGC, nCount, IpDocName, NULL) 


This escape informs the device driver that a new print job is starting and that all sub- 
sequent NEWFRAME escape calls should be spooled under the same job until an 
ENDDOC escape call occurs. This ensures that documents longer than one page will not 
be interspersed with other jobs. 


Parameter Type/Description 
hDC HDC Identifies the device context. 
nCount short Specifies the number of characters in the string pointed 


to by the IpDocName parameter. 


lpDocName LPSTR Points to a null-terminated string that specifies the 
name of the document. The document name is displayed in the 
Print Manager window. The maximum length of this string is 31 
characters plus the terminating null character. 


The return value specifies the outcome of the escape. It is —-1 if an error such as insufficient 
memory or an invalid port specification occurs. Otherwise, it is positive. 


The correct sequence of events in a printing operation is as follows: 


1. Create the device context. 


2. Set the abort function to keep out-of-disk-space errors from terminating a printing 
operation. 


An abort procedure that handles these errors must be set by using the SETABORT- 
PROC escape. 


3. Begin the printing operation with the STARTDOC escape. 


4. Begin each new page with the NEWFRAME escape, or each new band with the 
NEXTBAND escape. 
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5. End the printing operation with the ENDDOC escape. 

6. Destroy the cancel dialog box, if any. 

7. Free the procedure-instance address of the abort function. 

If an application encounters a printing error or a canceled print operation, it must not at- 
tempt to terminate the operation by using the Escape function with either the ENDDOC 


or ABORTDOC escape. GDI automatically terminates the operation before returning the 
error value. 


TRANSFORM_CTM 


Syntax 


Return Value 


Comments 


short Escape(hDC, TRANSFORM_CTM, 36, /pMatrix, NULL) 


This escape modifies the current transformation matrix. The current transformation matrix 
controls the manner in which coordinates are translated, rotated, and scaled by the device. 
By using matrices, you can combine these operations in any order to produce the desired 
mapping for a particular picture. 


The new current transformation matrix will contain the product of the matrix referenced by 
the JpMatrix parameter and the previous current transformation matrix (CTM = M x CTM). 


Parameter Type/Description 
hDC HDC Identifies the device context. 
[pMatrix LPSTR Points to a 3-by-3 array of 32-bit integer values speci- 


fying the new transformation matrix. Entries in the matrix are 
scaled to represent fixed-point real numbers. Each matrix entry 
is scaled by 65,536. The high-order word of the entry contains 
the whole integer portion, and the low-order word contains the 
fractional portion. 


The return value is TRUE if the escape was successful and FALSE if it was unsuccessful. 


Applications should not make any assumptions about the initial value of the current trans- 
formation matrix. 


The matrix specification used for this escape is based on the Microsoft OS/2 Presentation 
Manager graphics programming interface (GPI) model, which is an integer-coordinate sys- 
tem similar to the one used by GDI. 


Chapter | Assembly-Language 
13 | Macros Overview 


Assembly-language Microsoft Windows applications are highly structured as- 
sembly-language programs that use high-level-language calling conventions as 
well as Windows functions, data types, and programming conventions. Although 
you create assembly-language Windows programs by using the Microsoft Macro 
Assembler, the goal is to generate object files that are similar to the object files 
generated by the C Compiler. This chapter gives some guidelines that can help 
you meet this goal when creating assembly-language Windows applications. 


The SDK includes the file CMACROS.INC. This file contains high-level-lan- 
guage macros that define segments, programming models, function interfaces, 
and data types needed to create Windows applications. The Cmacros provide as- 
sembly-time options that define the memory model and the calling conventions 
that the application will use. The options must be selected in the assembly-lan- 
guage source file prior to the INCLUDE directive. 


This chapter provides an overview of the Cmacros and supplies important infor- 
mation on creating an assembly-language Windows application. The chapter 
covers the following topics: 

= How to create an assembly-language Windows application 


m An overview of the Cmacros 


= How to use the Cmacros in an assembly- uaa application 


13. 1 Guidelines for Creating Assembly-Language Windows 
Applications 


When creating an assembly-language Windows application using the Cmacros, 


you should add the following to your application’s assembly-language source 
file: 


1. Specify the memory model by setting one of the options memS, memM, 
memC, or memL to 1. 


2. Specify the Pascal calling convention by setting the 7PLM option to 1. 
This is required for functions that will be called by Windows. 
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3. Enable the Windows prolog and epilog by setting the ?WIN option to 1. 


This is required for callback functions or for exported functions in Windows 
libraries. 


4. Include the CMACROS.INC file in the application source file. 


The statement that includes the CMACROS.INC file must come after the 
statements described in the preceding steps. 


5. Create the application entry point, WinMain, and make sure that it is declared 
a public function. 


6. Declare any callback functions as described in Section 13.1.6, “Declaring 
Callback Functions.” 


7. After assembling the application source files, link your application’s as- 
sembled object files with the appropriate C-language library for Windows 
and C run-time libraries. 


The rest of this section describes these steps in more detail. 


13.1.1 Specifying a Memory Model 


The Cmacro memory-model options specify the memory model that the applica- 
tion will use. The memory model defines how many code and data segments are 
in the application. The following is a list of the possible memory models: 


Model Description 

Small One code segment and one data segment. 

Medium Multiple code segments and one data segment. 
Compact One code segment and multiple data segments. 
Large Multiple code and data segments. 

Huge Multiple code segments and multiple data segments 


with one or more data items larger than 64K. 


Select a memory model by defining the option name at the beginning of the as- 
sembly-language source file. Table 13.1 shows the option names available: 
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Table 13.1 Memory Options 


Option Memory Code Data 
Name Model Size Size 

memS small small small 
memM medium large small 
memC compact small large 
memL large large large 
memH huge large large 


You can define a name by using the EQU directive. The definition has the fol- 
lowing form: 


memM EQU 1 
If no option is selected, the default model is small. 
When you select a memory-model option, two symbols are defined. These two 


symbols can be used for code that is dependent on the memory model: 


SizeC 0 = small code 
1 = large code 


SizeD 0 = small data 
1 = large data 


2 = huge data 


13.1.2 Selecting a Calling Convention 


The Cmacro calling-convention option specifies the high-level-language calling 
convention that the application will use. You can select the calling convention by 
defining the value of the symbol ?PLM. Table 13.2 lists the values and conven- 
tions. 


Table 13.2 Calling Conventions 


?PLM value Convention Description 


0 Standard C The caller pushes the rightmost argument onto the 
stack first, the leftmost last. The caller pops the ar- 
guments off the stack after control is returned. 


1 Pascal The caller pushes the leftmost argument onto the 
stack first, the rightmost last. The called function 
pops the arguments off the stack. 
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You can set the 7PLM symbol value by using the = directive. The statement has 
the following form: 


?PLM = 1 


The default is the Pascal calling convention. The Pascal calling convention is re- 
quired for functions that are called by Windows. 


13.7.3 Enabling the Windows Prolog/Epilog Option 


The Windows prolog/epilog option is required for Windows applications. It speci- 
fies whether to use special prolog and epilog code with each function; this code 
defines the current data segment for the given function. 


. 


You set this option by defining the value of the symbol ?WIN. Table 13.3 lists 
the values: 


Table 13.3. Prolog/Epilog Code Options 


?WIN value Meaning 
0 Disables the special prolog/epilog code. 
1 Enables the special prolog/epilog code. 


You can set the ?WIN symbol value by using the = directive. The statement has 
the following form: 


2WIN = 1 


By default, the prolog and epilog code are enabled. 


13.1.4 Including the File CMACROS.INC 


The file CMACROS.INC contains the assembly-language definitions for all the 
Cmacro macros. You must include this file at the beginning of the assembly-lan- 


guage source file by using the INCLUDE directive. The line has the following 
form: 


INCLUDE CMACROS.INC 


You must give the full pathname if the macro file is not in the current directory 
or in a directory specified on the command line. 


For a complete description of each of the Cmacro macros, see Chapter 14, “‘As- 
sembly-Language Macros Directory.” 
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13.1.5 Creating the Application Entry Point 


Create the application entry point, WinMain, and make sure that it is declared a 
public function. It should have the following form: 


cProc WinMain, <PUBLIC>, <si,di> 
parmW hInstance 
parmW hPrevInstance 
parmD IlpCmdLine 
parmW nCmdShow 
cBegin WinMain 


cEnd WinMain 
sEnd 


The WinMain function should be defined within the standard code segment 
CODE. 


13.1.6 Declaring Callback Functions 


Make sure any callback functions are declared as follows: 


cProc TestWndProc, <FAR,PUBLIC>, <si,di> 
parmW hWnd 
parmW message 
parmW wParam 
parmD 1Param 
cBegin TestWndProc 


cEnd TestWndProc 


Callback functions must be defined within a code segment. 


13.1.7 Linking with Libraries 


After assembling your application’s source files, you should link the assembled 
object files with the appropriate C-language libraries. 


If the entire application is written in assembly language, to link properly you may 
need to add an external definition for the absolute symbol __acrtused in your 
application source file. 
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13.1.8 Enabling Stack Checking 


You can enable stack checking by defining the symbol ?CHKSTK. When stack 
checking is enabled, the prolog code calls the externally defined routine 
CHKSTK to allocate local variables. 


You can define the ?CHKSTK symbol by using the = directive. The statement 
has the following form: ° 


?CHKSTK = 1 
Once CHKSTK is defined, stack checking is enabled for the entire file. 
The default (when CHKSTK is not defined) is no stack checking. | 


13.2 Cmacro Groups 


Chapter 14, “Assembly-Language Macros Directory,” lists and describes the 
Cmacro macros, a set of assembly-language macros that can be used with the 
Microsoft Macro Assembler (MASM) to create assembly-language Windows 
applications. The Cmacros provide a simplified interface to the function and seg- 
ment conventions of high-level languages such as C. 


The Cmacros are divided into the following groups: 


= Segment macros 

= Storage-allocation macros 
= Function macros 

= Call macros 

m Special-definition macros 


= Error macros 


The rest of this section briefly describes each group of macros. 


13.2.1 Segment Macros 


Segment macros give access to the code and data segments that an application 
will use. These segments have the names, attributes, classes, and groups required 
by Windows. 


The Cmacros have two predefined segments, named CODE and DATA, that any 
application can use without special definition. 
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Macro Name 


createSeg 
sBegin 
sEnd 


assumes 


dataOFFSET 


codeOFFSET 


segNameOFFSET 


13.2.2 Storage-Allocation Macros 


Description 


Creates a new segment that has the specified name 
and segment attributes. 


Opens up a segment (this macro is similar to the 
SEGMENT assembler directive). 


Closes a segment (this macro is similar to the ENDS 
assembler directive). 


Makes all references to data and code in the segment 
segName relative to the segment register given by 
segReg. It is similar to the ASSUME assembler 
directive. 


Generates an offset relative to the start of the group 
to which the DATA segment belongs. It is similar to 
the OFFSET assembler operator, but automatically 
provides the group name. 


Generates an offset relative to the start of the group 
to which the CODE segment belongs. It is similar to 
the OFFSET assembler operator, but automatically 
provides the group name. 


Generates an offset relative to the start of the group 
to which the user-defined segment segName 

belongs. It is similar to the OFFSET assembler oper- 
ator, but automatically provides the group name. 


Storage-allocation macros allocate static memory (either private or public), de- 
clare externally defined memory and procedures, and allow the definition of 


public labels. 


Macro Name 
staticX 
globalX 
externxX 


labelX 


Description 
Allocates private static-memory storage. 
Allocates public static-memory storage. 


Defines one or more names that will be the labels of 
external variables or functions. 


Defines one or more names that will be the labels of 


public (global) variables or functions. 
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13.2.3 Function Macros 


Function macros define the names, attributes, parameters, and local variables of 


functions. 

Macro Name Description 

cProc Defines the name and attributes of a function. 

parmxX Defines one or more function parameters. The para- 
meters provide access to the arguments passed to the 
function. : 

localX Defines one or more frame variables for the 
specified function. 

cBegin Defines the actual entry point for the specified func- 
tion. 

cEnd Defines the exit point for the specified function. 


13.2.4 Call Macros 


Call macros can be used to call cProc functions and high-level-language func- 
tions. These macros pass arguments according to the calling convention defined 


by the ?PLM option. 

Macro Name Description 

cCall Pushes the specified arguments onto the stack, saves 
registers (if any), and calls the specified function. 

Save Directs the next cCall macro to save the specified 

. registers on the stack before calling a function, and 

to restore the registers after the function returns. 

Arg This macro defines the arguments to be passed to a 


function by the next cCall macro. 


13.2.5 Special-Definition Macros 


Special-definition macros inform the Cmacros about user-defined variables, func- 
tion-register use, and register pointers. 
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Macro Name Description 


Def Registers the name of a user-defined variable with 
the Cmacros. 


FarPtr Defines a 32-bit pointer value that can be passed as 
a single argument in a cCall macro. 


13.2.6 Error Macros 


Error macros generate an error message to the console and an error message in 
the listing. Both the text that caused the error and the result of its evaluation are 
displayed in the generated error message. 


Error macros let you code assertions into an assembly-language source program. 
This lets you code optimum instruction sequences for some operations based on 
the variable allocation or bit position of flag in a word, and assert that the as- 
sumptions made are true. 


Macro Name Description 


errnz Evaluates a given expression. If the result is not 
zero, an error is displayed. 


errn$ Subtracts the offset of the /abel parameter from the 
offset of the location counter, then adds the bias 
parameter to the result. If this result is not zero, then 
an error message is displayed. 


13.3 Using the Cmacros 


This section explains the assembly-language statements generated by some of the 
Cmacros and illustrates their use with an example of a Cmacros function called 
BITBLT. 


13.3.1 Overriding Types 


Parameters and local variables created using the parmX and localX macros actu- 
ally correspond to expressions of the following form: 


localB x == x equ byte ptr [bptnn] 
parmB y == y equ byte ptr [bp+nn] 


In this example, the nn parameter specifies an offset from the current bp register 
value. 
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These expressions let you use the names without having to explicitly type in 
“type ptr” and “[bp+offset]” operators. This means that “x” can be referred to as 
follows: 


mov al ,Xx 


and that “y” can be referred to as follows: 


mov ax,y 


A problem arises if the type must be overridden. The assembler creates an error 
message if it encounters the following line: 


mov ax,word ptr x 


This can be solved by enclosing the name in parentheses: 
mov ax,word ptr (x) 


One exception to this pattern is the localV macro. The expression generated by 
this macro does not have a type associated with it. Therefore it can be overridden 
without the parentheses. For example: 


localV horse,1@ ==> horse equ [bp+nn] 


13.3.2 Symbol Redefinition 


Any symbol defined by a parmX macro in one function can be redefined as a 
parameter in any other function. This allows different functions to refer to the 
same parameter by the same name, regardless of its location on the stack. 


13.3.3 Cmacros: a Sample Function 


The following example defines the assembly function BITBLT, which is a FAR 
and PUBLIC type function. When BITBLT is invoked, the SI and DI registers 
are automatically saved, and automatically restored upon exit. The BP register is 
always saved. 


BITBLT is passed'seven double-word pointers on the stack. Space will be allo- 
cated on the stack for eight frame variables (one structure, five bytes, and two 
words). 


The cBegin macro defines the start of the actual code. The pExt parameter is 
loaded, and some values are loaded into registers. The AX and BX registers are 
saved on the following cCall. 


Another C function, There, is invoked by the cCall macro. Four arguments are 
passed to There: pDestBitmap, the 32-bit pointer in DS:SI, register AX, and 
register BX. The cCall macro places the arguments on the stack in the correct 
order. 
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When There returns, the arguments placed on the stack are automatically 
removed, and the AX and BX registers are restored. 


When cEnd is reached, the frame variables are removed, any autosave registers 
are restored, and a return of the correct type (near or far) is performed. 


The following example shows how the BITBLT function is defined: 


cProc BITBLT,<FAR,PUBLIC>,<si,di> 


parmD 
parmD 
parmD 
parmD 
parmD 
parmD 
parmD 


localV 
localB 
localB 
localB 


localW 
localW 


localB 
localB 


cBegin 


lds 
mov 
mov 


RegPtr 
Save 


cCall 


pDestBitmap s—> to dest bitmap descriptor 
pDestOrg ;—-> to dest origin (a point) 
pSrcBitmap ;-> to source bitmap descriptor 
pSrcOrg s—> to source origin 

pExt :—> to rectangle extent 

pRop 3-> to rasterop descriptor 
pBrush ;—> to a physical brush 

nOps ,4 ;# of each operand used 

phaseH ;Horizontal phase (rotate count) 
PatRow ;Current row for patterns [@..7] 
direction sIncrement/decrement flag 
startMask smask for first dest byte 
lastMask smask for last dest byte 
firstFetch sNumber of first fetches needed 
stepDirection ;Direction of move (left, right) 
Si,pExt 


ax,extentx[si] 
bx,extentYL[si] 


dest,ds,si 
<ax,bx> 


THERE, <pDestBitmap,dest,ax,bx> 


extentX[si],cx 
extentY[si],dx 
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13.4 Summary 


The CMACROS.INC file defines segments, programming models, function 
interfaces, and data types needed to create Windows applications. The Cmacros 
provide assembly-time options that define the memory model and the calling con- 
ventions that the application will use. For more information on topics related to 
the Cmacros, see the following: 


Topic Reference 

Cmacro descriptions Reference, Volume 2: Chapter 14, 
“Assembly-Language Macros Directory” 

Using the linker Tools: Chapter 2, “Linking Applications: The 
Linker” 

Using the Macro Assembler Microsoft Macro Assembler Programmer’s 


Guide 


Chapter 


14 


Assembly-Language 
Macros Directory 


This chapter describes the Cmacros, a set of assembly-language macros that 
can be used with the Microsoft Macro Assembler (MASM) to create assembly- 
language Windows applications. The Cmacros provide a simplified interface to 
the function and segment conventions of high-level languages such as C. 


This section lists the Cmacros in alphabetical order, and describes each macro in 
detail. 


Arg 
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Arg 
Syntax 


Comments 


Examples 


assumes 
Syntax 


Examples 


cBegin 
Syntax 


Arg namelist 


This macro defines the arguments to be passed to a function by the next cCall macro. The 
arguments are pushed onto the stack in the order given. This order must correspond to the 
order of the function parameters. 


More than one Arg macro can be given before each cCall. Multiple Arg macros have the 
same effect as a single macro. 


The namelist parameter specifies a list of argument names to be passed to the function. All 
names must have been previously defined. 


Byte-type parameters are passed as words. There is no sign extension or zeroing of the 
high-order byte. 


Immediate arguments are not supported. 


Arg varl 

Arg var2 

Arg var3 | 

Arg <varl,var2,var3> 


assumes segReg, segName 


This macro makes all references to data and code in the segment segName relative to the 
segment register given by segReg. It is similar to the ASSUME assembler directive. 


The segReg parameter specifies the name of a segment register. 


The segName parameter specifies the name of a predefined segment, CODE or DATA, or 
a user-defined segment. 


assumes CS, CODE 
assumes DS, CODE 


cBegin [procName] 


This macro defines the actual entry point for the function procName. The macro creates 
code that sets up the frame and saves registers. 


14-3 cCall 
The optional procName parameter specifies a function name. If it is given, it must be the 
same as the name given in the cProc macro immediately preceding the cBegin macro. 

cCall 

Syntax cCall procName, [[<argList>]], [<underscores>]] 

This macro pushes the arguments in argList onto the stack, saves registers (if any), and 
calls the function procName. 

The procName parameter specifies the name of the function to be called. 

The optional argList parameter specifies a list of the names of arguments to be passed to 
the function. This list is not required if the Arg macro is used before cCall. 

The optional underscores parameter specifies whether an underscore should be added to 
the beginning of procName. If this argument is blank and the calling convention is the C 
calling convention, an underscore is added. 

Comments The arguments of an Arg macro are pushed onto the stack before any arguments in the ar- 
gList parameter of a cCall macro. 

Byte-type parameters are passed as words. There is no sign extension or zeroing of the 
high-order byte. 
Immediate arguments are not supported. 

Examples cCall there,<pExt,ax,bx,pResult> 
Arg pExt 
Arg ax 
cCall there,<bx,pResult> 

cEnd 

Syntax cEnd [[procName] 


This macro defines the exit point for the procName function. The macro creates code that 
discards the frame, restores registers, and returns to the caller. 


The optional procName parameter specifies a function name. If it is given, it must be the 
same as the name given in the cBegin macro immediately preceding the cEnd macro. 


Once a function has been defined using cProc, any formal parameters should be declared 
with the parmX macro and any local variables with the localX macro. The cBegin and 
cEnd macros must be used to delineate the code for the function. 
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The following is an example of a complete function definition: 


Example cProc strcpy,<PUBLIC>,<si,di> 
parmW = dst 
parmwW src 
localW cnt 


cBegin 
cld 
mov si,src 
mov di,dest 
push ds 
pop es 
xor CX, CX 
mov cnt,cx 
loop: 
lodsb 
stosb 
inc cnt 
cmp al,@ 
jnz loop 
mov ax,cnt 
cEnd 
codeOFFSET 
Syntax codeOFFSET arg 
This macro generates an offset relative to the start of the group to which the CODE seg- 
ment belongs. It is similar to the OFFSET assembler operator, but automatically provides 
the group name. For this reason, it should be used instead of OFFSET. 
The arg parameter specifies a label name or offset value. 
Example mov ax,codeOFFSET label 
cProc 
Syntax cProc procName, <attributes>, <autoSave> 


This macro defines the name and attributes of a function. 
The procName parameter specifies the name of the function. 


The attributes parameter specifies the function type. It can be a combination of the follow- 
ing: 
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createSeg 


Comments 


Examples 


createSeg 
Syntax 


Type Description 


NEAR A near function. It can only be called from the segment in 
which it is defined. 


FAR A far function. It can be called from any segment. 


PUBLIC A public function. It can be externally declared in other 
source files. 


The default attribute is NEAR and private (i.e., cannot be declared externally in other 
source files). The NEAR and FAR attributes cannot be used together. If more than one at- 
tribute is selected, the angle brackets are required. 


The autoSave parameter specifies a list of registers to be saved when the function is in- 
voked, and restored when exited. Any of the 8086’s registers can be specified. 


If this function is called by a function written in C, it must save and restore the SI and DI 
registers. 


The BP register is always saved, regardless of whether it is present in the autoSave list. 


cProc procl, <FAR, ds,es> 
cProc proc2, <NEAR,PUBLIC> 
cProc proc3,,ds 


createSeg segName, logName, align, combine, class 


This macro creates a new segment that has the specified name and segment attributes. The 
macro automatically creates an assumes macro and an OFFSET macro for the new seg- 
ment. This macro is intended to be used in medium-model Windows applications to define 
nonresident segments. The segName parameter specifies the actual name of the segment. 
This name is passed to the linker. 


The JogName parameter specifies the logical name of the segment. This name is used in all 
subsequent sBegin, sEnd, and assumes macros that refer to the segment. 


The align parameter specifies the alignment type. It can be any one of the following: 


dataOFFSET | ae 


Example 


Comments 


dataOFFSET 
Syntax 


Example 


The combine parameter specifies the combine type for the segment. It can be any one of 
the following: 


COMMON 
MEMORY 
PUBLIC 
STACK 


If no combine type is given, a private segment is assumed. 


The class parameter specifies the class name of the segment. The class name defines 
which segments must be loaded in consecutive memory. 


createSeg _INIT, INITCODE, BYTE, PUBLIC, CODE 


sBegin INITCODE 
assumes CS: INITCODE 


mov ax,initcodeOFFSET sample 


sEnd INITCODE 


The alignment, combine type, and class name are described in detail in the Microsoft 
Macro Assembler Reference . . 


The Cmacros have two predefined segments, named CODE and DATA, that any applica- 
tion can use without special definition. Medium-, large-, and huge-model applications can 
define additional segments by using the createSeg macro. 


dataOFFSET arg 


This macro generates an offset relative to the start of the group to which the DATA seg- 
ment belongs. It is similar to the OFFSET assembler operator, but automatically provides 
the group name. For this reason, it should be used instead of OFFSET. 


The arg parameter specifies a label name or offset value. 


mv ax,dataOFFSET label 
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DefX 
Syntax DefX <namelist> 
This macro registers the name of a user-defined variable with the Cmacros. Variables that 
are not defined using the staticX, globalX, externX, parm X, or locaLX macros cannot be 
referred to in other macros unless the name is registered, or the variable was defined with 
the DW assembler directive. 
The X parameter specifies the storage size of the variable. It can be any one of the follow- 
ing: 
Type Description 
B Byte 
Ww Word 
D Double-word 
Q Quad-word 
T Ten-byte word 
CP Code pointer (one word for small and compact models) 
DP Data pointer (one word for small and medium models) 
The namelist parameter specifies a list of variable names to be defined. 
Example maxSize db 132 
DefB maxSize 
dest equ wordptr es:[di] 
DefW dest 
errn$ 
Syntax errn$ label, [[bias]] 


This macro subtracts the offset of Jabel from the offset of the location counter, then adds 
bias to the result. If this result is not zero, then an error message is displayed. 


The /abel parameter specifies a label corresponding to a memory location. 


The optional bias parameter specifies a signed bias value. A plus or minus sign is required. 


errnz 
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Example 


errnz 
Syntax 


Examples 


: end of previous code 
errn$ functionl 
functionl: 


If a function that was originally located immediately after another piece of code is ever 
moved, errn$ displays an error message. 


errmz <expression> 
This macro evaluates a given expression. If the result is not zero, an error is displayed. 


The expression parameter specifies the expression to be evaluated. The angle. brackets are 
required if there are any spaces in the expression. 


x db q 
y db ? 
mov ax, word ptr x 


errnz <COFFSED -y¥) = COPRPSET x) 21> 


If during assembly, x and y receive anything but sequential storage locations, errnz dis- 
plays an error message. 


tablel struc 


tablellen equ $-tablel 
tablel ends 


table2 struc 


table2len equ $-table2 
table2 ends 


errnz tablelLen-table2Len 


If during assembly, the length of two tables is not the same, errnz displays an error 
message. 
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— externX 
Syntax externX <namelist> 
This macro defines one or more names that will be the labels of external variables or func- 
tions. 
The X parameter specifies the storage size or function type. It can be any one of the follow- 
ing: 
Type Description 
A Constant value declared with the EQU and = directives in a 
separate file 
B Byte 
Ww Word 
D Double-word 
Q Quad-word 
T Ten bytes 
CP Code pointer (one word for small and compact models) 
DP Data pointer (one word for small and medium models) 
NP Near function pointer 
FP Far function pointer 
P Near for small and compact models; far for other models 
The namelist parameter specifies the list of the names of the variables or functions. 
Examples externB <DataBase> 
externFP <SampleRead> 
FarPtr 
Syntax FarPtr name, segment, offset 


This macro defines a 32-bit pointer value that can be passed as a single argument in a 
cCall macro. In the FarPtr macro, the segment and offset values do not have to be in 
registers. 


The name parameter specifies the name of the pointer to be created. 
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The segment parameter specifies the text that defines the segment portion of the pointer. 


The offset parameter specifies the text that defines the offset portion of the pointer. 


Example FarPtr destPtr,es,<wordptr 3[si]> 
cCall proc,<destPtr,ax> 


globalX 


Syntax globalX name, [linitialValue]] [replication] 
This macro allocates public static-memory storage. 
The X parameter specifies the size of the storage to be allocated. It can be any one of the 
following: 
Type | Description 
B Byte 
Ww Word 
D Double-word 
Q Quad-word 
T Ten bytes 
CP Code pointer (one word for small and compact models) 


DP Data pointer (one word for small and medium models) 


The name parameter specifies the reference name of the allocated memory. 


The optional initialValue parameter specifies an initial value for the storage. The default is 
zero if no value is specified. 


The optional replication parameter specifies a count of the number of times the allocation 
is to be duplicated. This parameter generates the DUP assembler operator. 


Examples globalW flag,1l 
globalB string,@, 3@ 
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labelX 
Syntax labelX <namelist> 
This macro defines one or more names that will be the labels of public (global) variables 
or functions. 
The X parameter specifies the storage size or function type. It can be any one of the follow- 
ing: 
Type Description 
B Byte 
Ww Word 
D Double-word 
Q Quad-word 
T Ten bytes 
CP Code pointer (one word for small and compact models) 
DP Data pointer (one word for small and medium models) 
NP Near function pointer 
FP Far function pointer 
7p Near for small and compact models; far for other models 
The namelist parameter specifies the list of the names of the external variables or func- 
tions. 
Examples labelB <DataBase> 
labelFP <SampleRead> 
localxX 
Syntax localX <namelist>, size 


This macro defines one or more frame variables for the function. To keep the words in the 
stack aligned, the macro ensures that the total space allocated is an even number of bytes. 
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The X parameter specifies the storage size. It can be any one of the following: 


Type ; Description 

B Byte (allocates a single byte of storage on the stack) 
Ww Word (allocated on a word boundary) 

D Double-word (allocated on a word boundary) 

V Variable size (allocated on a word boundary) 

Q | Quad-word (aligned on a word boundary) 

T Ten-byte word (aligned on a word boundary) 

CP Code pointer (one word for small and compact models) 
DP Data pointer (one word for small and medium models) 


The namelist parameter specifies the list of the names of the frame variables for the func- 
tion. 


The size parameter specifies the size of the variable. It is used with localV only. 


Comments B-type variables are not necessarily aligned on word boundaries. 


The localD macro creates two additional symbols, OFF_name and SEG_name. 
OFF _name is the offset portion of the parameter; SEG_name is the segment portion. 


Only the name is required when referencing a variable. Write your code like this: 


mov al,varl 
Not like this: 


mov al,byte ptr varl[bp] 


Examples localB <L1,L2,L3> 
localW L4 
localD <L5> 
localV L6,%(size struc) 
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parmxX 
Syntax parmX <namelist> 
This macro defines one or more function parameters. The parameters provide access to the 
arguments passed to the function. Parameters must appear in the same order as the argu- 
ments in the function call. 
The X parameter specifies the storage size. It can be any one of the following: 
Type Description 
B Byte (allocated on a word boundary on the stack) 
WwW Word (allocated on a word boundary) 
D | Double-word (allocated on a word boundary) 
Q Quad-word (aligned on a word boundary) 
T Ten-byte word (aligned on a word boundary) 
CP Code pointer (one word for small and compact models) 
DP Data pointer (one word for small and medium models) 
The namelist parameter specifies the list of the parameter names. 
Comments The parmD macro creates two additional symbols, OFF_name and SEG_name. 
OFF _name is the offset portion of the parameter; SEG_name is the segment portion. 
Only the parameter name is required when referring to the corresponding argument. Write 
your code like this: 
mov al,varl 
Not like this: 
mov al,byte ptr varl[bp] 
Examples parmW varl 


parmB <var2,var3,var4> 
parmD <var5> 
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Save 
Syntax Save <regList> 
This macro directs the next cCall macro to save the specified registers on the stack before 
calling a function, and to restore the registers after the function returns. The macro can be 
used to save registers that are destroyed by the called function. 
The Save macro applies to only one cCall macro; each new cCall must have a correspond- 
ing Save macro. If two Save macros appear before a cCall, only the second macro is recog- 
nized. 
The regList parameter specifies a list of registers to be saved. 
Examples Save <cl,bh,si> 
Save <ax> 
sBegin 
Syntax sBegin segName 
This macro opens up a segment. It is similar to the SEGMENT assembler directive. 
The segName parameter specifies the name of the segment to be opened. It can be one of 
the predefined segments, CODE or DATA, or the name of a user-defined segment. 
Examples sBegin DATA 
sBegin CODE 
segNameOFFSET 
Syntax segNameOFFSET arg 


Example 


This macro generates an offset relative to the start of the group to which the user-defined 
segment segName belongs. It is similar to the OFFSET assembler operator, but automati- 
cally provides the group name. For this reason, it should be used instead of OFFSET. 


The arg parameter specifies a label name or offset value. 


mv ax,initcodeOFFSET label 


14-15 


sEnd 


sEnd 
Syntax 


Examples 


staticX 
Syntax 


Examples 


sEnd [segName] 
This macro closes a segment. It is similar to the ENDS assembler directive. 


The optional segName parameter specifies a name used for readability. If it is given, it 
must be the same as the name given in the matching sBegin macro. 


sEnd 
sEnd DATA 


staticX name, [linitialValue]], {[replication] 

This macro allocates private static-memory storage. 

The X parameter specifies the size of storage to be allocated. It can be any one of the fol- 
lowing: 

Type Description 

B Byte 

WwW Word 

D Double-word 

Q Quad-word 

T Ten bytes 

CP Code pointer (one word for small and compact models) 

DP Data pointer (one word for small and medium models) 

The name parameter specifies the reference name of the allocated memory. The optional in- 


itialValue parameter specifies an initial value for the storage. If no value is specified, the 
default is zero. 


The optional replication parameter specifies a count of the number of times the allocation 
is to be duplicated. This parameter generates the DUP assembler operator. 


StaticW flag,l 
staticB string, , 39 


Chapter 
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Windows DDE Protocol 


The Microsoft Windows Dynamic Data Exchange (DDE) protocol defines the 
method for communicating among applications. This communication takes place 
as applications send messages to each other to initiate conversations, to request 
and share data, and to terminate conversations. This chapter describes these mes- 
sages and the rules associated with their use. It also briefly describes several clip- 
board formats which a DDE application can register for use ina DDE 
conversation. 


Guide to Programming provides an overview of DDE programming, including 
such concepts as client, server, application, topic and item. It also introduces the 
modes of DDE communication, including permanent data links, one-time trans- 
fers, and remote command execution, and it explains the flow of DDE messages. 


Conventions Used in This Chapter 


Message-specific argument names bear prefixes indicating their type, as follows: 


Prefix. Description 

a An atom of word length (16 bits); for example, aName. 

cf A registered clipboard format number (word length); for 
example, cfFormat. 

f A flag bit; for example, fName. 

h A handle (word length) to a global memory object; for 


example, hName. 


Ww Any other word-length argument; for example, wName. 


15.1 Using the DDE Message Set 


Each DDE message has two parameters. The first parameter, wParam (word 
length), carries the handle of the sender’s window; it is the same in all cases and 
so is not shown in Table 15.1. The second parameter, /Param (a long word, 32 
bits), is composed of a low-order word and a high-order word containing 
message-specific arguments, as follows: 
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Table 15.1 DDE Messages 


Arguments in /Param 


Message Low-order word High-order word 
WM_DDE_ACK 

In reply to INITIATE aApplication aTopic 

In reply to EXECUTE wStatus hCommands 

All other messages wStatus altem 
WM_DDE_ADVISE hOptions altem 
WM_DDE_DATA hData altem 
WM_DDE_EXECUTE (Reserved) hCommands 
WM_DDE_INITIATE aApplication aTopic 
WM_DDE_POKE hData altem 
WM_DDE_REQUEST cfFormat altem 
WM_DDE_TERMINATE (Reserved) (Reserved) 
WM_DDE_UNADVISE (Reserved) altem 


An application calls the SendMessage function to issue the WM_DDE_INIT- 
IATE message ora WM_DDE_ACK message sent in response to 
WM_DDE_INITIATE. All other messages are sent using the PostMessage 
function. The window handle of the receiving window appears as the first para- 
meter of these calls. The second parameter contains the message to be sent, the 
third parameter identifies the sending window, and the fourth parameter contains 
the message-specific arguments. For example: 


PostMessage(hwndRecipient, WM_DDE_MESSAGE, hwndSender, 
MAKELONG(Tow_word, high_word)) 


The MAKELONG macro combines low_word and high_word into a long word. 


15.2 Synchronizing the DDE Conversation 


An application window that processes DDE requests from the window of a DDE 
partner must process them strictly in the order in which they are received from 
that partner. However, when handling messages from multiple DDE partners, the 
window does not have to follow this “first in, first out” rule. In other words, only 
the conversations themselves must be synchronous; the window can shift from 
one conversation to another asynchronously. 


For example, suppose the following messages are in a window’s queue: 
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Message from window X 
Message from window Y 
Message from window X 


The window must process message | before message 3, but it need not process 
message 2 before message 3. If window Y is a lower-priority DDE-conversation 
partner than window X, the window can defer processing the messages from 
window Y until it has finished dealing with the messages sent by window X. The 
following shows acceptable processing orders for these messages and the relative 
priority implied by each order: 


Order Relative Priority 


1 2 3. £4Window X = window Y 
1 3 2  £4Window X > window Y 


2 1 #3. Window X < window Y 


If an application is unable to process an incoming request because it is waiting 
for a DDE response, it must posta WM_DDE_ACK message with the fBusy 
flag set to 1 to prevent deadlock. An application can also send a busy 
WM_DDE_ACK message if for any reason the application cannot process 

an incoming request within a reasonable amount of time. 


An application should be able to deal with the situation in which its DDE partner 
fails to respond with a message within a certain time-out interval. Since the 
length of this interval may vary depending on the nature of the application and 
the configuration of the user’s system (including whether it is on a network), the 
application should provide a way for the user to specify the time-out interval. 


15.3 Using Atoms 


Certain arguments of DDE messages (altem, aTopic, and aApplication) are 

global atoms. Applications using these atoms must explicitly delete them to 
purge them from the atom list. Section 15.7, “DDE Message Directory,” de- 
scribes the rules for allocating and deleting atoms used by each message. 


In all cases, the sender of a message must delete any atom which the intended 
receiver will not receive due to an error condition, such as failure of the Post- 
Message function. 
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15.4 Using Shared Memory Objects 


DDE uses shared memory objects for three purposes: 


= To carry a data item value to be exchanged. This is an item referenced by the 
hData argument in the WM_DDE_DATA and WM_DDE_POKE messages. 


= To carry options in a message. This is an item referenced by the hOptions ar- 
gument ina WM_DDE_ADVISE message. 


= Tocarry an execution-command string. This is an item referenced by the 
hCommands argument in the WM_DDE_EXECUTE message and its corre- 
sponding WM_DDE_ACK message. 


Applications that receive a DDE shared memory object must treat it as read only. 
It must not be used as a mutual read/write area for the free exchange of data. 


As with a DDE atom, a shared memory object should be freed properly to pro- 
vide for effective memory management. Shared memory objects should be prop- 
erly locked and unlocked. Section 15.7, “DDE Message Directory,” describes the 
rules for allocating and deleting shared memory objects used by each message. 


In all cases, the sender of a message must delete any shared memory object 
which the intended receiver will not receive due to an error condition, such as 
failure of the PostMessage function. 


15.5 Using Clipboard Formats 


You can pass data by means of any of the standard clipboard formats or with a 
registered clipboard formats. See the description of the SetClipboardData func- 
tion in Chapter 4, “Functions Directory,” in Reference, Volume 1, for more infor- 
mation on standard clipboards. See the description of the RegisterClipboard- 
Format function for information on registering clipboard formats. 


A special, registered format named Link is used to identify an item in a DDE 
conversation. For more information, see Guide to Programming. 


15.6 Using the System Topic 


Applications are encouraged to support at all times a special topic with the name 
System. This topic provides a context for items of information that may be of 
general interest to another application. 


The following list contains suggested items for the System topic. This list is not 
exclusive. The data item values should be rendered in the CF_TEXT format. 
Individual elements of a System topic item value should be delimited by tab 
characters. 
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Item 


SyslItems 


Topics 


Return Message 


Status 


Formats 


Description 


A list of the System-topic items supported by the appli- 
cation. 


A list of the topics supported by the application at the 
current time; this list can vary from moment to mo- 
ment. 


Supporting detail for the most recently used 
WM_DDE_ACK message. This is useful when more 
than eight bits of application-specific return data are 
required. 


An indication of the current status of the application. 
When a server receives a WM_DDE_ REQUEST 
message for this System-topic item, it should respond 
by posting a WM_DDE_DATA message with a string 
containing either “Busy” or “Ready,” as appropriate. 


A list of clipboard format numbers that the application 
can render. 


15.7 DDE Message Directory 


This section describes the nine DDE messages. Included in each description is a 
list of the message-specific arguments and the rules for posting and receiving 
each message. The SDK contains the DDE.H header file which defines the DDE 
messages and data structures described in this section. 
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WM_DDE_ACK 


This message notifies an application of the receipt and processing of a WM_DDE_IN- 
ITIATE, WM_DDE_EXECUTE, WM_DDE_DATA, WM_DDE_ADVISE, 
WM_DDE_UNADVISE, or WM_DDE_POKE message, and in some cases, of a 
WM_DDE_REQUEST message. 


Parameter 


wParam 


lParam 


Description 


Identifies the sending window. 


The meaning of the low-order and high-order words depends on 
the message to which the WM_DDE_ACK message is respond- 


ing. 


When responding to WM_DDE_INITIATE: 


Argument 


aApplication 


aTopic 


Description 


Low-order word of /Param. An atom that 
contains the name of the replying applica- 
tion. 


High-order word of /Param. An atom 
that contains the topic with which the re- 
plying server window is associated. 


When responding to WM_DDE_EXECUTE: 


Argument 


wStatus 


hCommands 


Description 


Low-order word of /Param. A series of 
flags that indicate the status of the re- 
sponse. 


High-order word of /Param. A handle 
that identifies the data item containing 
the command string. 
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Parameter Description 


When replying to all other messages: 


Argument Description 

wStatus Low-order word of /Param. A series of 
flags that indicate the status of the re- 
sponse. 

altem High-order word of /Param. An atom 


that specifies the data item for which the 
response is sent. 


Comments The wStatus word consists of a DDEACK data structure that contains the following infor- 
mation: 
Bit Name Meaning 
15 fAck 1 = Request accepted. 


0 = Request not accepted. 


14 fBusy 1 = Busy. An application is expected to set 
fBusy if it is unable to respond to the request at 
the time it is received. The fBusy flag is defined 
only when fAck is zero. 


0 = Not busy. 
13-8 Reserved for Microsoft use. 
7-0 bAppReturnCode Reserved for application-specific return codes. 
Posting Except in response to the WM_DDE_INIT IATE message, post the WM_DDE_ACK 


message by calling the PostMessage function, not SendMessage. When responding to 
WM_DDE_INITIATE, send the WM_DDE_ACK message with SendMessage. 


When acknowledging any message with an accompanying a/tem atom, the application that 
sends WM_DDE_ACK can reuse the a/tem atom that accompanied the original message, 
or it may delete it and create a new one. 


When acknowledging WM_DDE_EXECUTE, the application that sends WM_DDE_ACK 
should reuse the hCommands object that accompanied the original WM_DDE_EXECUTE 
message. 
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If an application has initiated the termination of a conversation by sending 
WM_DDE_TERMINATE and is awaiting confirmation, the waiting application should not 
acknowledge (positively or negatively) any subsequent message sent by the other applica- 
tion. The waiting application should delete any atoms or shared memory objects received 
in these intervening messages. 


Receiving The application that receives WM_DDE_ACK should delete all atoms accompanying the 
message. 


If the application receives WM_DDE_ACK in response to a message with an accompany- 
ing hData object, the application should delete the hData object. 


If the application receives a negative WM_DDE_ACK message sent in reply to a 
WM_DDE_ADVISE message, the application should delete the hOptions object sent with 
the original WM_DDE_ADVISE message. 


If the application receives a negative WM_DDE_ACK message sent in reply toa. 
WM_DDE_EXECUTE message, the application should delete the hCommands object sent 
with the original WM_DDE_EXECUTE message. 


WM_DDE_ADVISE 


This message, posted by a client application, requests the receiving (server) application to 
supply an update for a data item whenever it changes. 


Parameter Description 
wParam Identifies the sending window. 
[Param Identifies the requested data and specifies how the data is to be 
sent. 
Argument Description 
hOptions Low-order word of /Param. A handle to 
a global memory object that specifies 
how the data is to be sent. 
altem High-order word of /Param. An atom 
that specifies the data item being re- 
quested. 
Comments The global memory object identified by hOptions consists of a DDEADVISE data struc- 


ture that contains the following: 
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Word Name Content 

1 fAckReq If bit 15 is 1, the receiving (server) application 
is requested to send its WM_DDE_DATA mes- 
sages with the ACK-requested bit (fAckReq) 
set. This offers a flow-control technique 
whereby the client application can avoid over- 
load from incoming DATA messages. 

fDeferUpd If bit 14 is 1, the server is requested to send its 
WM_DDE_DATA messages with a null /Data 
handle. These messages are alarms telling the 
client that the source data has changed. Upon re- 
ceiving one of these alarms, the client can 
choose to call for the latest version of the data 
by issuing a WM_DDE_REQUEST message, 
or it can choose to ignore the alarm altogether. 
This would typically be used when there is a 
substantial resource cost associated with render- 
ing and/or assimilating the data. 

reserved Bits 13-0 are reserved. 

2 cfFormat The client’s preferred type of data. Must be a 
standard or registered clipboard data format 
number. 

If an application supports more than one clipboard format for a single topic and item, it 
can post multiple WM_DDE_ADVISE messages for the topic and item, specifying a differ- 
ent clipboard format with each message. . 

Posting Post the WM_DDE_ADVISE message by calling the PostMessage function, not Send- 

Message. 

Allocate hOptions by calling the GlobalAlloc function with the GEMEM_DDE_SHARE 
option. 

Allocate altem by calling the GlobalAddAtom function. 

If the receiving (server) application responds with a negative WM_DDE_ACK message, 

the sending (client) application must delete the hOptions object. 

Receiving Post the WM_DDE_ACK message to respond positively or negatively. When posting 


WM_DDE_ACK, reuse the a/tem atom or delete it and create a new one. If the 
WM_DDE_ACK message is positive, delete the hOptions object; otherwise, do not delete 
the object. 
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WM_DDE_DATA 


This message, posted by a server application, sends a data item value to the receiving 
(client) application, or notifies the client of the availability of data. 


Parameter 
wParam 


lParam 


Description 


Identifies the sending window. 


Identifies the available data and specifies how it is sent. 


Argument 


hData 


altem 


Description 


Low-order word of /Param. A handle 
that identifies the global memory object 
containing the data and additional infor- 
mation. The handle should be set to 
NULL if the server is notifying the client 
that the data item value has changed 
during a “warm link.” A warm link is es- 
tablished by the client sending a 
WM_DDE_ADVISE message with the 
f{DeferUpd bit set. 


High-order word of /Param. An atom 
that identifies the data item for which 
data or notification is sent. 


Comments The global memory object identified by hData consists of a DDEDATA data structure that 


contains the following: 


Word Name 
1 fAckReq 
reserved 


Content 


If bit 15 is 1, the receiving (client) application 
is expected to send a WM_DDE_ACK message 
after the WM_DDE_DATA message has been 
processed. If bit 15 is zero, the client applica- 
tion should not send a WM_DDE_ACK 
message. 


Bit 14 is reserved. 
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Word Name Content 

fRelease If bit 13 is 1, the client application is expected 
to free the hData memory object after pro- 
cessing it. If bit 13 is zero, the client application 
should not free the object. See the “Posting” 
and “Receiving” sections for exceptions. 

fRequested If bit 12 is 1, this data is offered in response to a 
WM_DDE_REQUEST message. If bit 12 is 
zero, this data is offered in response to a 
WM_DDE_ADVISE message. 

reserved Bits 11-0 are reserved. 

2 cfFormat This specifies the format in which the data are 
sent or offered to the client application. It must 
be a standard or registered clipboard data for- 
mat. 

3-n Value[ ] This is the data. It is in the format specified by 
cfFormat. 

Posting Post the WM_DDE_DATA message by calling the PostMessage function, not SendMes- 
sage. 

Allocate hData by calling the GlobalAlloc function with the GMEM_DDESHARE option. 

Allocate altem by calling the GlobalAddAtom function. | 

If the receiving (client) application responds with a negative WM_DDE_ACK message, 

the sending (server) application must delete the hData object. 

If the sending (server) application sets the fRelease flag to zero, the sender is responsible 

for deleting hData upon receipt of either a positive or negative acknowledgement. 

Do not set both the fAckReq and fRelease flags to zero. If both flags are set to zero, it is 

difficult for the sending (server) application to determine when to delete hData. 

If fAckReq is 1, post the WM_DDE_ACK message to respond positively or negatively. 


Receiving 


When posting WM_DDE_ACK, reuse the a/tem atom or delete it and create a new one. 
If fAckReq is zero, delete the altem atom. 


If the sending (server) application specified hData as NULL, the receiving (client) applica- 
tion can request the server to send the actual data by posting a WM_DDE_REQUEST 
message. 
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After processing the WM_DDE_DATA message in which hData is not NULL, delete 
hData unless either of the following conditions is true: 


m= The fRelease flag is zero. 


= The fRelease flag is 1, but the receiving (client) application responds with a negative 
WM_DDE_ACK message. 


WM_DDE_EXECUTE 


Comments 


This message, posted by a client application, sends a string to a server application to be 
processed as a series of commands. The server application is expected to post a 
WM_DDE_ACK message in response. 


Parameter Description 
wParam Identifies the sending window. 
lParam Specifies the commands to be executed. 
Argument Description 
reserved The low-order word of /Param is re- 
served. 
hCommands High-order word of /Param. A handle 


that identifies a global memory object 
containing the command(s) to be ex- 
ecuted. 


The command string is null-terminated. The command string should adhere to the syntax 
shown below. Optional syntax elements are enclosed in double brackets ([[ ]]); single brack- 
ets ([ ]) are a syntax element. 


[opcodestring] [[ [opcodestring] ] ... 
The opcodestring uses the following syntax: 
opcode (parameter [| parameter ]| ... ) J] 


The opcode is any application-defined single token. It may not include spaces, commas, 
parentheses, or quotation marks. 


The parameter is any application-defined value. Multiple parameters are separated by com- 
mas, and the entire parameter list is enclosed in parentheses. The parameter may not in- 
clude commas or parentheses except inside a quoted string. If a bracket or parenthesis 
character is to appear in a quoted string, it must be doubled: ((. 
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The following examples show valid command strings: 


[connect ][download(queryl,results.txt)][disconnect] 
[query("sales per employee for each district") ] 
Lopen("sample.xlm")J][Lrun("rici")] 


Posting Post the WM_DDE_EXECUTE message by calling the PostMessage function, not Send- 
Message. 


Allocate hCommands by calling the GlobalAlloc function with the 
GMEM_DDE_SHARE option. 


When processing WM_DDE_ACK sent in reply to WM_DDE_EXECUTE, the sender of 
the original WM_DDE_EXECUTE message must delete the hCommands object sent back 
in the WM_DDE_ACK message. 


Receiving Post the WM_DDE_ACK message to respond positively or negatively, reusing the hCom- 
mands object. 


WM_DDE_INITIATE 


This message, sent by either a client or server application, initiates a conversation with 
applications responding to the specified application and topic names. 


Upon receiving this message, all applications with names that match the aApplication 
application and that support the aTopic topic are expected to acknowledge it (see the 
WM_DDE_ACK message). 


Parameter Description 
wParam Identifies the sending window. 
lParam Specifies the target application and the topic. 
Argument Description 
aApplication Low-order word of /Param. An atom that 


specifies the name of the application 
with which a conversation is requested. 
The application name may not contain 
slashes or backslashes. These characters 
are reserved for future use in network im- 
plementations. If the application name is 
NULL, a conversation with all applica- 
tions is requested. 
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Parameter Description 

Argument Description 

aTopic High-order word of /Param. An atom 
that specifies the topic for which a con- 
versation is requested. If the topic is 
NULL, a conversation for all available 
topics is requested. 

Comments If the aApplication argument is NULL, any application may respond. If the aTopic argu- 


ment is NULL, any topic is valid. Upon receiving a WM_DDE_INITIATE request with a 
null topic, an application is expected to send a WM_DDE_ACK message for each of the 
topics it supports. 


Sending Send the WM_DDE_INITIATE message by calling the SendMessage function, not the 
PostMessage function. Broadcast the message to all windows by setting the first para- 
meter of SendMessage to —1, as shown: 


SendMessage(-1,WM_DDE_INITIATE,hwndClient ,MAKELONG(aApp,aTopic)); 


If the application has already obtained the window handle of the desired server, it can send 
WM_DDE_INITIATE directly to the server window by passing the server’s window 
handle as the first parameter of SendMessage. 


‘Allocate aApplication and aTopic by calling GlobalAddAtom. 


When SendMessage returns, delete the aApplication and aTopic atoms. 


Receiving To complete the initiation of a conversation, respond with one or more WM_DDE_ACK 
messages, where each message is for a separate topic. When sending WM_DDE_ACK 
message, create new aApplication and aTopic atoms; do not reuse the atoms sent with the 
WM_DDE_INITIATE message. 


WM_DDE_POKE 


This message, posted by a client application, requests the receiving (server) application to 
accept an unsolicited data item value. 


The receiving application is expected to reply with a positive WM_DDE_ACK message if 
it accepts the data, or with a negative WM_DDE_ACK message if it does not. 
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WM_DDE_POKE 


Comments 


Posting 


Parameter 


wParam 


[Param 


Description 


Identifies the sending window. 


Identifies the data and specifies how it is sent. 


Argument 


hData 


altem 


Description 


Low-order word of /Param. A handle 
that specifies the global memory object 
containing the data and other informa- 
tion. 


High-order word of /Param. An atom 
that identifies the data item offered to the 
server application. 


The global memory object identified by hData consists of a DDEPOKE data structure that 
contains the following: 


Word 
1 


Name 
reserved 


fRelease 


reserved 


cfFormat 


Value[ ] 


Content 


Bits 15-14 are reserved. 


If bit 13 is 1, the receiving (server) application 
is expected to free the memory object after pro- 
cessing it. If bit 13 is zero, the receiving 
application should not free the object. See the 
following “Posting” and “Receiving” sections 
for exceptions. 


Bits 12-0 are reserved. 


This specifies the client’s preferred type of data. 
It must be a standard or registered clipboard 
data format. 


This is the data. It is in the format specified by 
cfFormat. 


Post the WM_DDE_POKE message by calling the PostMessage function, not SendMes- 


sage. 


Allocate hData by calling the GlobalAlloc function with the GMEM_DDESHARE option. 


Allocate altem by calling the GlobalAddAtom function. 
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If the receiving (server) application responds with a negative WM_DDE_ACK INCSSHEE 
the sending (client) application must delete the hData object. 


If the sending (client) application sets the fRelease flag to zero, the sending application 
must delete hData upon receiving either a positive or negative WM_DDE_ACK message. 


Receiving Post the WM_DDE_ACK message to respond positively or negatively. When posting 
WM_DDE_ACK, reuse the a/tem atom or delete it and create a new one. 


After processing the WM_DDE_POKE message, delete hData unless either of the follow- 
ing conditions is true: 


= The fRelease flag is zero. 


m= The fRelease flag is 1, but the receiving (server) application responds with a negative 
WM_DDE_ACK message. 


WM_DDE_REQUEST 


This message, posted by a client application, requests the receiving (server) application to 
provide the value of a data item. 


Parameter Description 
wParam Identifies the sending window. 
lParam Specifies the requested data and the clipboard format number for 
the data 
Argument Description 
cfFormat Low-order word of /Param. A standard 
or registered clipboard format number. 
altem High-order word of /Param. An atom 
that specifies which data item is being re- 
quested from the server. 
Posting Post the WM_DDE_REQUEST message by calling the PostMessage function, not Send- 
Message. 


Allocate altem by calling the GlobalAddAtom function. 
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WM_DDE_TERMINATE 


Receiving 


If the receiving (server) application can satisfy the request, it responds with a 
WM_DDE_DATA message containing the requested data. Otherwise, it responds with a 
negative WM_DDE_ACK message. 


When responding with either a WM_DDE_DATA or a _DDE_ACK message, reuse the 
altem atom or delete it and create a new one. 


WM_DDE_TERMINATE 


Posting 


Receiving 


This message, posted by either a client or server application, terminates a conversation. 


Parameter Description 
wParam Identifies the sending window. 
[Param Is reserved. 


Post the WM_DDE_TERMINATE message by calling the PostMessage function, not 
SendMessage. 


While waiting for confirmation of the termination, the sending application should not ac- 
knowledge any other messages sent by the receiving application. If the sending application 
receives messages (other than WM_DDE_TERMINATE) from the receiving application, it 
should delete any atoms or shared memory objects accompanying the messages. 


Respond by posting a WM_DDE_TERMINATE message. 


WM_DDE_UNADVISE 


This message, sent by a client application, informs a server application that the specified 
item, or a particular clipboard format for the item, should no longer be updated. This termi- 
nates the warm or hot link for the specified item. 


Parameter Description 
wParam Identifies the sending window. 


lParam Specifies the data-request item to be canceled. 
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Posting 


Receiving 


Parameter Description 


Argument ’ Description 


altem High-order word of /Param. An atom 
that specifies the data for which the up- 
date request is being retracted. When 
altem is NULL, all active 
WM_DDE_ADVISE conversations as- 
sociated with the client are to be 
terminated. 


cfFormat Low-order word of /Param. The clip- 
board format of the item that specifies 
the clipboard format for which the up- 
date request is being retracted. When 
cfFormat is NULL, all active 
WM_DDE_ADVISE conversations for 
the item are to be terminated. 


Post the WM_DDE_UNADVISE message by calling the PostMessage function, not Send- 
Message. 


Allocate altem by calling the GlobalAddAtom function. 


Post the WM_DDE_ACK message to respond positively or negatively. When posting 
WM_DDE_ ACK, reuse the a/tem atom or delete it and create a new one. 
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Appendix A 
Virtual-Key Codes 


The following list shows the symbolic constant names, hexadecimal values, and 
descriptive information for Microsoft Windows virtual-key codes. The codes are 
listed in numeric order. 


Name Value Description 
VK_LBUTTON 01H Left mouse button 
VK_RBUTTON 02H Right mouse button 
VK_CANCEL 03H Used for control-break processing 
VK_MBUTTON 04H Middle mouse button (3-button 
mouse) 
0SH-07H Undefined 
VK_BACK 08H BACKSPACE key 
VK_TAB 09H TAB key © 
OAH-O0BH Undefined 
VK_CLEAR OCH CLEAR key 
VK_RETURN 0ODH RETURN key 
VK_SHIFT 10H SHIFT key 
VK_CONTROL 11H CONTROL key 
VK_MENU 12H MENU key 
VK_PAUSE 13H PAUSE key 
VK_CAPITAL 14H CAPITAL key 
15H-19H Reserved for Kanji systems 
1AH Undefined 
VK_ESCAPE 1BH ESCAPE key 
1CH-1FH Reserved for Kanji systems 
VK_SPACE . 20H SPACEBAR 
VK_PRIOR 21H PAGE UP key 
VK_NEXT 22H PAGE DOWN key 
VK_END 23H END key 
VK_HOME 24H HOME key 
VK_LEFT 25H LEFT ARROW key 
VK_UP 26H UP ARROW key 
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Name Value Description 


VK_RIGHT 27H RIGHT ARROW key 
VK_DOWN 28H DOWN ARROW key 
VK_SELECT 29H SELECT key 
2AH OEM specific 
VK_EXECUTE 2BH EXECUTE key 
VK_SNAPSHOT 2CH PRINTSCREEN key for Windows 
version 3.0 and later 
VK_INSERT 2DH INSERT key 
VK_DELETE 2EH DELETE key 
VK_HELP 2FH HELP key 
VK_0 30H 0 key 
VK_1 31H 1 key 
VK_2 32H 2 key 
VK_3 . 33H 3 key 
VK 4 _ 34H 4 key 
VK_5 35H 5 key 
VK_6 36H 6 key 
VK_7 37H 7 key 
VK_8 38H 8 key 
VK_9 39H 9 key 
3AH-40H Undefined 
VK_A 41H A key 
VK_B 42H B key 
VK_C 43H C key 
VK_D _ 44H D key 
VK_E 45H E key 
VK_F 46H F key 
VK_G 47H G key 
VK_H 48H H key 
VK _I 49H I key 
VK_J 4AH J key 
VK_K 4BH K key 
VK_L 4CH L key 
VK_M 4DH M key 
VK_N 4EH ~ N key 


VK_O 4FH O key 
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Name Value Description 
VK_P 50H P key 
VK_Q 51H Q key 
VK_R 52H R key 
VK_S 53H S key 
VK_T 54H T key 
VK_U 55H U key 
VK_V 56H V key 
VK_W 57H W key 
VK_X 58H x key 
VK_Y 59H Y key 
VK_Z 5AH Z key 

SBH-5FH Undefined 
VK_NUMPADO 60H Numeric key pad 0 key 
VK_NUMPAD1 61H Numeric key pad 1 key 
VK_NUMPAD2 62H Numeric key pad 2 key 
VK_NUMPAD3 63H Numeric key pad 3 key 
VK_NUMPAD4 64H Numeric key pad 4 key 
VK_NUMPADS5 65H Numeric key pad 5 key 
VK_NUMPAD6 66H Numeric key pad 6 key 
VK_NUMPAD7 67H Numeric key pad 7 key 
VK_NUMPAD8 68H Numeric key pad 8 key 
VK_NUMPAD9 69H . Numeric key pad 9 key 
VK_MULTIPLY 6AH Multiply key 
VK_ADD 6BH Add key 
VK_SEPARATER 6CH Separater key 
VK_SUBTRACT | 6DH Subiract key 
VK_DECIMAL 6EH Decimal key 
VK_DIVIDE 6FH Divide key 
VK_F1 70H Fl key 
VK_F2 71H F2 key 
VK_F3 72H F3 key 
VK_F4 73H F4 key. 
VK_F5 74H F5 key 
VK_F6 75H F6 key 
VK_F7 76H F7 key 


VK_F8 77H F8 key 
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Name Value Description 
VK_F9 78H F9 key 
VK_F10 79H F10 key 
VK_F11 7AH F11 key 
VK_F12 7BH F12 key 
VK_F13 7CH F13 key 
VK_F14 7DH F14 key 
VK_F15 7EH F15 key 
VK_F16 7FH F16 key 
80H-87H OEM specific 
88H-8FH Unassigned 
VK_NUMLOCK 90H NUM LOCK key 
VK_OEM_SCROLL 91H SCROLL LOCK key 
92H-B9H Unassigned 
VK_OEM_1 BAH Keyboard-specific punctuation key 
(may not appear on every keyboard) 
VK_OEM_PLUS BBH Plus (+) key 
VK_OEM_COMMA BCH Comma (,) key 
VK_OEM_MINUS ‘BDH Minus (—) key 
VK_OEM_PERIOD BEH Period (.) key 
VK_OEM_2 BFH Keyboard-specific punctuation key 
(may not appear on every keyboard) 
VK_OEM_3 COH Keyboard-specific punctuation key 
(may not appear on every keyboard) 
C1H-DAH Unassigned 
VK_OEM_4 DBH Keyboard-specific punctuation key 
(may not appear on every keyboard) 
VK_OEM_5 DCH Keyboard-specific punctuation key 
(may not appear on every keyboard) 
VK_OEM_6 DDH Keyboard-specific punctuation key 
(may not appear on every keyboard) 
VK_OEM_7 DEH Keyboard-specific punctuation key 
(may not appear on every keyboard) 
VK_OEM_8 DFH Keyboard-specific punctuation key 
(may not appear on every keyboard) 
EQH-E1H OEM specific 
VK_OEM_102 E2H <> or \| on enhanced, non-U.S. 


IBM®@-compatible 102-key keyboard 
E3H-E4H OEM specific 


Name 


E6H 

E7H-E8H 
E9H-F5H 
F6H-FEH 


Description 


Unassigned 
OEM specific 
Unassigned 
OEM specific 
Unassigned 
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Appendix B 
RC Diagnostic Messages 


This appendix contains descriptions of diagnostic messages produced by the 
Resource Compiler (RC). Many of these messages appear when the Resource 
Compiler is not able to compile your resources. The descriptions in this appendix 
can help you determine the problem. 


A (V) symbol at the beginning of a message description indicates that the 
message is displayed only if RC is run with the —V (verbose) option. These 
messages are generally informational and do not necessarily indicate errors. 


See Chapter 8, “Rescource Script Statements,” for information on the key words 
and fields specified in this appendix. 


The messages are listed in alphabetical order. 


Accelerator Type required (ASCII or VIRTKEY) 
The type field in the ACCELERATORS statement must contain either the 
ASCII or VIRTKEY value. 

BEGIN expected in Accelerator Table 
The BEGIN key word must immediately follow the ACCELERATORS 
key word. 

BEGIN expected in Dialog 
The BEGIN key word must immediately follow the DIALOG key word. 


BEGIN expected in menu 
The BEGIN key word must immediately follow the MENU key word. 


BEGIN expected in RCData 
The BEGIN key word must immediately follow the RCDATA key word. 


BEGIN keyword expected in String or Error Table 


The BEGIN key word must immediately follow the STRINGTABLE or 
ERRTABLE key word. 


Cannot Reuse String Constants 


You are using the same value twice ina STRINGTABLE or ERRTABLE 
statement. Make sure you are not mixing overlapping decimal and hexadecimal 
values. 
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Control Character out of range [4A - 4Z] 


A control character in the ACCELERATORS statement is invalid. The 
character following the caret (“) must be between A and Z, inclusive. 


copy of temp-file-2 to exe-file failed 
The temporary file was not able to create the new .EXE file. Make sure that the 
TEMP environment variable is pointing to a drive that is not write-protected. 
Copying segment id (size bytes) 
(V) RC is copying the specified segment to the .EXE file. 


Could not find RCPP.EXE 


RCPP.ERR must be in the current directory or a directory in the PATH environ- 
ment. 


Could not open in-file-name 


RC could not open the specified file. Make sure the file exists and that you typed 
the filename correctly. 


Couldn’t open resource-name 


RC could not open the specified file. Make sure the file exists and that you typed 
the filename correctly. 


Couldn’t write executable 


The .EXE file could not be copied to the temporary file. Make sure that the 
TEMP environment variable is pointing to a drive that is not write-protected and 
that the .EXE file from the linker is correct. You can check the .EXE file with the 
EXEHDR program. 


Creating resource-name 


(V) RC is creating a new .RES file. 


Empty menus not allowed 


An END key word appears before any menu items are defined in the MENU 
statement. Empty menus are not permitted by the Resource Compiler. Make sure 
you do not have any open quotation marks within the MENU statement. 


END expected in Dialog 


The END key word must occur at the end of a DIALOG statement. Make sure 
there are no open quotes left from the preceding statement. 
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END expected in menu 


The END key word must come at the end of a MENU statement. Make sure you 
do not have any open quotation marks or a mismatched pair of BEGIN and END 
statements. 


Error: Bitmap file resource-file is not in 3.00 format. 


Use SDKPaint to convert version 2.x resource files to the 3.0 format. 


Error Creating resource-name 


Error 


Error 


Error 


Error 


Error 


Could not create specified .RES file. Make sure it is not being created on a read- 
only drive. Use the —V option to find out whether the file is being created. 


: I/O error reading file. 


Read failed. Since this is a generic routine, no specific filename is supplied. 


: I/O error seeking in file 


Seeking in file failed. 


: I/O error writing file. 


Write failed. Since this is a generic routine, no specific filename is supplied. 


: Old DIB in resource-name. Pass it through SDKPAINT. 


The resource file specified is not compatible with Windows 3.0. Make sure you 
have read and saved this file using the latest version of SDKPaint. 


: Out of memory. Try not using resources with string identifiers. 


There is not enough memory to allocate for a table of string names. You can 
view these names are when you use the —V option. Try to replace the string 
names with numbers. For example, you can change 


MYICON ICON myicon.ico 

to * 
1 ICON myicon.ico 

or provide the following statement in your header file: 


#tdefine MYICON 1 


Error: Resource file resouce-name is not in 3.00 format. 


Make sure your icons and cursors have been read and saved using the latest 
version of SDKPaint. 
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Errors in .EXE file 


LINK failed. See the CodeView and Utilities manual in the Microsoft C 5.1 
Optimizing Compiler documentation set for more information. 


.EXE file too large; relink with higher /ALIGN value 


The EXE file is too large. Relink the .EXE file with a larger /ALIGN value. If 
the .EXE file is larger than 800K, you should use.the /ALIGN:32 value on your 
LINK line. 


.EXE not created by LINK 


You must create the .EXE file with a version of LINK that is from C version 5.1 
or later. 


Expected Comma in Accelerator Table 


RC requires a comma between the event and idvalue fields in the ACCEL- 
ERATORS statement. 


Expected control class name 


The class field of a CONTROL statement in the DIALOG statement must be 
one of the following types: BUTTON, COMBOBOX, EDIT, LISTBOX, 
SCROLLBAR, STATIC, or user-defined. Make sure the class is spelled correctly. 


Expected font face name 


The typeface field of the FONT option in the DIALOG statement must be an 
ASCII character string enclosed in double quotation marks. This field specifies 
the name of a font. 


Expected ID value for Menuitem 


The MENU statement must contain a menulD field, which specifies the name or 
number that identifies the menu resource. 


Expected Menu String 


Each MENUITEM and POPUP statement must contain a text field, which is a 
string enclosed. in double quotation marks that specifies the name of the menu 
item or pop-up menu. AMENUITEM SEPARATOR statement requires no 
quoted string. 


Expected numeric command value 
RC was expecting a numeric idvalue field in the ACCELERATORS statement. 
-. Make sure you have used a #define constant to specify the value and that the con- 
stant is spelled correctly. 
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Expected numeric constant in string table 


A numeric constant, defined in a #define statement, must immediately follow the 
BEGIN key word ina STRINGTABLE or ERRTABLE statement. 


Expected numeric point size 


The pointsize field of the FONT option in the DIALOG statement must be an in- 
teger point size value. 


Expected Numerical Dialog constant 
A DIALOG statement requires integer values for the x, y, width, and height 
fields. Make sure these values are included after the DIALOG key word and that 
they are not negative. 

Expected String in STRINGTABLE/ERRTABLE 
A string is expected after each stringid value ina STRINGTABLE or 
ERRTABLE statement. 

Expected String or Constant Accelerator command 
RC was not able to determine what kind of key is being set up for the accel- 
erator. The event field in the ACCELERATORS statement might be invalid. 

Expecting number for ID 


Expecting a number for the id field of a control statement in the DIALOG state- 
ment. Make sure you have a number or #define statement for the control ID. 


Expecting quoted string in dialog class 


The class field of the CLASS option in the DIALOG statement must be an in- 
teger or a string, enclosed in double quotation marks. 


Expecting quoted string in dialog title 
The captiontext field of the CAPTION option in the DIALOG statement must 
be an ASCII character string enclosed in double quotation marks. 

File not found: fileame 
The file specified in the RC command line was not found. Check to see whether 
the file has been moved to another directory and whether the filename or 
pathname is typed correctly. 

Font names must be ordinals 


The pointsize field in the FONT statement must be an integer, not a string. 
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Gangload area is [size] bytes at offset 0x[address] 


(V) This is the size (in bytes) of all the segments that have one of the following 
attributes: 


= PRELOAD 
= DISCARDABLE 
= Code segments that contain the entry point, WinMain 


= Data segments (which should not be discardable) 


The segments are placed in a continguous area in the .EXE file for fast loading. 
The offset value is from the the beginning of the file. To disable gangloading, use 
the —k option. 

Insufficient memory to spawn RCPP.EXE 


There wasn’t enough memory to run the preprocessor (RCPP). You can try not 
running any memory-resident software that might be taking up too much 
memory. Use the CHKDSK program to verify the amount of memory you have. 


Invalid Accelerator 
An event field in the ACCELERATORS statement was not recognized or was 
more than two characters in length. 

Invalid Accelerator Type (ASCII or VIRTKEY) 

| The type field in the ACCELERATORS statement must contain either the 
ASCII or VIRTKEY value. 

Invalid control character . 
A control character in the ACCELERATORS statement is invalid. A valid con- 
trol character consists of one letter (only) following a caret (4). 

Invalid Control type 


Each control statement ina DIALOG statement must be one of the following: 
CHECKBOX, COMBOBOX, CONTROL, CTEXT, DEFPUSHBUTTON, 
EDITTEXT, GROUPBOX, ICON, LISTBOX, LTEXT, PUSHBUTTON, 
RADIOBUTTON, RTEXT, SCROLLBAR. 


Make sure these control statements are spelled correctly. 


Invalid .EXE file 


The .EXE file is invalid. Make sure that the linker created it correctly and that 
the file exists. You can check the .EXE file with the EXEHDR program. 
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Invalid switch, option 
You used an option that was not valid. Use RC —? for a list of the command-line 
options. 

Invalid type 
The resource type was not among the types defined in the WINDOWS .H file. 


Invalid usage. Use rc —? for Help 
Make sure you have at least one filename to work with. Use RC —? for a list of 
the command-line options. 

No executable filename specified. 


The —FE option was used, but no .EXE filename specified. 


No resource binary filename specified. 


The -FO option was used, but no .RES filename specified. 


Not a Microsoft Windows format .EXE file 
Make sure that the linker created the .EXE file correctly and that the file exists. 
You can check the .EXE file with the EXEHDR program. 

Out of far heap memory 


There wasn’t enough memory. Try not running any memory-resident software 
that might be taking up too much space. Use the CHKDSK program to find out 
how much memory you have. 

Out of memory, needed v bytes 


RC was not able to allocate the specified amount of memory. 


RC: Invalid swap area size: -S string 


Invalid swap area size. Check your syntax for the -S option on the RC command 
line. The following are acceptable command lines: 


RG. S123 
RC S123K ;where K is kilobytes 
RC S123p ;where p is paragraphs 
RC: Invalid switch: option 
You used an option that was not valid. Use RC —? for a list of the command-line 
options. 
RC: RCPP preprocessor-command-string 
(V) RC is passing the specified string to the preprocessor. 
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RC: RCPP.ERR not found 
RCPP.ERR must be in the current directory or a directory in the PATH environ- 
ment. 

RC terminated by user 


A CONTROL+C key combination was pressed, terminating RC. 


RC terminating after preprocessor errors 
See the Microsoft C 5.1 Optimizing Compiler documentation for information 
about preprocessor errors. 

RCPP.EXE command line greater than 128 bytes 


The command line was too long. 


RCPP.EXE is not a valid executable 
RCPP.EXE is not valid. The file might have been altered. Try copying the file 
from the SDK disks. 

Reading resource-name 
(V) RC is reading the .RES file. 


Resources will be aligned on number byte boundaries 
(V) The alignment is determined by the ALIGN:number option on the LINK 
line. ; 

Sorting preload segments and resources into gangload section 


(V) RC is sorting the preloaded segments so that they can be loaded quickly. 


Text string or ordinal expected in Control 


The text field of a CONTROL statement in the DIALOG statement must be 
either a text string or an ordinal reference to the type of control is expected. If 
using an ordinal, make sure that you have a #define statement for the control. 


The EXETYPE of this program is not Windows 


The EXETYPE WINDOWS statement did not appear in the .DEF file. Since the 
linker might make optimizations for OS/2 (the default EXETYPE) that are not 
appropriate for Windows, the EXETYPE WINDOWS statement must be 
specified. 


Unable to create destination 


RC was not able to create the destination file. Make sure there is enough disk 
space. 


RC Diagnostic Messages B-9 


Unable to open exe-file 


RC could not open this .EXE file. Make sure that the linker created it correctly 
and that the file exists. 


Unbalanced Parentheses 


Make sure you have closed every open parenthesis in the DIALOG statement. 


Unexpected value in RCData 


The raw-data values in the RCDATA statement must be integers or strings, each 
separated by a comma. Make sure you did not leave out a comma or leave out a 
quotation mark around a string. 


Unknown DIB header format 


The bitmap header is not a BITMAPCOREHEADER or BITMAPINFO- 
HEADER structure. 


Unknown error spawning RCPP.EXE 


For an unknown reason, RCPP was not started. Try copying the file from the 
SDK disks, and use the CHKDSK program to verify the amount of available 
memory. 


Unknown Menu SubType 


The item-definition field of the MENU statement can contain only MENUITEM 
and POPUP statements. 


Warning: ASCII character not equivalent to virtual key code 


There is an invalid virtual-key code in the ACCELERATORS statement. The 
ASCII value for some characters (such as *, 4, &,) is not equivalent to the virtual- 
key code for the corresponding key. (In the case of the asterisk (*), the virtual- 
key code is equivalent to the ASCII value for 8, the numeric character on the 
same key. Therefore the statement 


VIRTREX *%: 7 


is invalid.) See Appendix A, “Virtual-Key Codes,” and Appendix D, “Character 
Tables,” for these values. 


Warning: Discardable segment id (hex-size bytes) is excessively large. 


The segment is greater than 27FFh in size. RC displays this warning because 
very large segments can adversely affect memory usage. Check your map file 
listing for the exact size of your segments. 
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Warning: SHIFT or CONTROL used without VIRTKEY 


The ALT, SHIFT, and CONTROL options apply only to virtual keys in the 
ACCELERATORS statement. Make sure you have used the VIRTKEY option 
with one of these other options. 


Writing resource resource-name or ordinal-id resource type (resource size) 


(V) RC is writing the resource name or ordinal ID, followed by a period and the 
resource type and size (in bytes). 


Warning: string segment number set to PRELOAD 


RC displays this warning when it copies a segment that must be preloaded but 
that is not marked PRELOAD in the linker .DEF file. 


All nondiscardable segments should be preloaded, including automatic data 
segments, fixed segments and the entry point of the code (WinMain). 


The attributes of your code segments are set by the .DEF file. Check your map 
file listing for more information. 


Appendix C 
Windows Debugging Messages 


The debugging version of Microsoft Windows generates diagnostic messages 
whenever it encounters an error that would otherwise cause the system to fail. 
Each diagnostic message has a unique number or string that identifies the cause 
of the message and potential failure. This appendix lists most of the diagnostic 
message names, their corresponding hexadecimal value, explains the meaning of 
each message, and in some cases suggests possible solutions. 


The messages are divided into three sections that correspond to the three 
Windows modules: User, GDI, and Kernel. The messages in each section are pro- 
duced by a function that is contained in the respective module. This division is 
necessary only because some messages in the User and GDI modules have the 
same error code. 


User Error Codes 


The error codes in this section are created by functions in the Windows User 
module. Some of these messages use the same codes as do GDI messages. Check 
the context of the error code to determine which module it is associated with. See 
the next section, “GDI Error Codes” for more information on differentiating 
these messages. ; 


Code Meaning 


1 Not enough memory was available for the requested allocation. Ask for a smaller 
’ amount of memory. Check HEAPWALK to see how much memory is free. 
Make sure you are not creating fixed objects that are fragmenting memory. 


2 Not enough memory was available for the requested reallocation. Do not attempt 
to call the LocalRealloc function to increase the size of your segment beyond 
64K. Avoid creating fixed objects that fragment memory. Make sure that the 
object is not discardable. 


4 The memory block could not be locked. Make sure the return value from your 
allocation function is a valid handle. Check HEAPWALK to see how much 
memory is free. Make sure you are not creating a fixed object that is fragmenting 
the memory. 


5 The memory block could not be unlocked. Make sure the block was locked to 
begin with. 
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6 An invalid handle was passed to a GDI function. This could occur for any GDI 
object. Check the value you obtain from the Create/Get GDI object to make sure 
it returned a valid value. 


7 The handle to the window you passed to the function was not valid. Use the 
IsWindow function to verify that the handle is valid and that the window has not 
been destroyed. 

8 The five preallocated display contexts (DCs) are in use. Make sure your 


application calls the ReleaseDC function to release a DC when the application is 
done with it. If ReleaseDC is not called, the DC will not be available to the 
system or any application. 


9 The DefWindowProc function was not found in your application. Place the 
DefWindowProc function in your application and make sure you are passing the 
correct parameters. 

A Some other application may have left the clipboard open. Pause and check again 


in a few seconds. Make sure your application calls the CloseClipboard function 
as soon as possible. Do not leave the clipboard open. 


B Your application attempted to destroy a window while it was still using a display 
context (DC). Make sure your application calls the ReleaseDC function to 
release a DC when the application is done with it. If ReleaseDC is not called, the 
DC will not be available to the system or any application. 


The keyboard driver did not initialize correctly. Rerun Setup. 


The mouse driver did not initialize correctly. Rerun Setup, or make sure that the 
mouse hardware did not get disconnected and that it is working outside of 
Windows. 


The display driver did not initialize correctly. Rerun Setup. 


An attempt was made to unlock the data segment but it wasn’t locked. Make sure 
the data segment is locked before trying to unlock it. 


16 The counter for windows of a particular class exceeded the limit of 32,767. Each 
time a window of a particular class is created, Windows increments a class usage 
counter. Each time a window of that class is destroyed, the counter is 
decremented. This message occurs in a CreateWindow or CreateWindowEx 
function. 


17 The counter for windows of a particular class became a negative number. See the 
preceding message for details. This message occurs in a DestroyWindow 
function. 
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18 


The counter for windows of a particular class was not zero when the class was 
destroyed. When an application or library terminates, Windows destroys all 
windows and classes created by that application or library. This error occurs if 
after the class is destroyed there still exists a window created by a different 
application or library that used the destroyed class. 


GDI Error Codes 


GDI errors occur when an invalid handle is passed to certain GDI functions. 
These errors can be identified by the existence of ValidateHandle in the back- 
trace. ValidateHandle is an internal Windows function that ensures that a handle 
is valid. Make sure you check for this function in order to differentiate GDI er- 
rors from User errors that have the same code number. (User messages are de- 
scribed in the previous section.) 


Meaning 
A GDI function received a NULL object handle. 


A valid handle is referencing an object that is not a valid GDI object or is a GDI 
object of the wrong type. This error often occurs when an object is deleted and 
the handle is reused for some other purpose in another GDI operation. 


The value of the error code depends on the type of object expected by the GDI 
function that generated the error. Each GDI object has a type identifier. Each 
GDI function that accepts an object as a parameter determines which object or 
objects are acceptable. To ensure that the handle it receives is valid, the GDI 
function calls ValidateHandle and passes it the handle and a range of acceptable 
type identifiers. If the handle references an object whose type identifier does not 
fall in the acceptable range, ValidateHandle generates an error code representing 
the lowest value of the range. 


For example, the SelectObject expects its first parameter to be a DC, a metafile 
DC, or and banding metafile DC. It passes this value, along with the range (7H to 
AH) to ValidateHandle. If the type identifier of the handle is not within that 
range, ValidateHandle produces an error code with the value 7H. 


The following list shows the type identifier of various objects: 


Type ID Object 
1 Pen 
2 Brush 
3 Font 
4 


Palette 
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Type ID Object 
5 Bitmap 
6 Region 
| Device context 
8 Disabled device context 
9 Metafile device context 
A Banding metafile device context 
B A window being destroyed had not released a DC that was obtained using the 
GetDC function. 


Kernel Error Codes 


The diagnostic messages in this section are associated with functions contained 
in the Windows Kernel module. These messages are listed in numerical order. 
Some numbers represent multiple messages. The retail version of Windows 
displays both the code number and the message text. The debugging version of 
Windows displays only the code number. 


Code Message 


FF gnotify - can’t discard segment 


This error is usually caused in real mode by a far call when the DS register is 
pointing to a fixed object. Windows will not be able to discard the code segment 
that made the call. 


This error can be produced by the following functions: GlobalReAlloc, 
GlobalAlloc (the wFlags parameter cannot contain GMEM_NOCOMPACT or 
GMEM_NODISCARD), GlobalCompact, GlobalDiscard, GlobalWire. 


FF Cannot GetProcAddress a task 


You cannot use the GetProcAddress call for a library or the calling task. 


FF MakeProcInstance only for current instance 
This message is displayed if you use MakeProclInstance to call the entry point 
of another task. 

FF MyOpenFile not reentrant 


Internal Windows error. 
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FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


gadd_free: Seg add not in range 


Unable to add segment to global free list. Your application has stepped over 
Windows’ memory. 


FREE MEMORY OVERWRITE AT 


Memory listed as free does not contain CC in each byte as expected. Put a break 
point at the specified address to find the problem. 


free_list: prev bad 


The free global memory list was corrupted by a wild write; the pointer from the 
previous entry in list does not point to the current entry. 


free_list: next bad 


The free global memory list was corrupted by a wild write; the pointer in the next 
entry does not point back to current entry. 


free_list: count bad 


The free global memory list was corrupted by a wild write; the final entry in the 
list does not match expected final entry. 


Heap frozen in INT 3F. 


Internal Windows error. 
LOCAL FREE MEMORY OVERWRITE AT 
The memory listed as free does not contain CC in each byte as expected. 


Automatic Data Segment larger than 64K. 


STACK + HEAP + STATICS combined are greater than 64K. Change the mod- 
ule-definition (. DEF) file. 


PatchCodeHandle, CORE DUMP FOLLOWS: 
Internal Windows error. 
Iru: prev bad 


The free global memory list was corrupted by a wild write; the pointer from the 
previous entry in the list does not point to current entry. 


Iru: next bad 


The free global memory list was corrupted by a wild write; the pointer in the next 
entry does not point back to the current entry. 
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FF Iru: count bad 


The free global memory list was corrupted by a wild write; the final entry in the 
list does not match the expected final entry. 


100 LocalAlloc : Invalid local heap 


A wild write corrupted the local heap. 


100 Ifreeadd : Invalid local heap 
Unable to add segment to the local free list. Your application has overwritten the 
local heap. 

100 function_name: Invalid local heap 


Lists the function at which the check is occurring (LocalAlloc, LocalLock, etc. &) 
and generally indicates an overwrite of the local heap list. 


103 Invalid local heap 


Either a wild write occurred or the LocalInit function was not performed cor- 
rectly. Leave some memory for Windows when calling LocalInit. 


140 Local heap is busy 


Two edit controls in the same dialog with the same ID value. Make sure that you 
don’t interchange decimal and hexadecimal numbers. 


140 EnterCrit: local heap is busy 
Internal Windows error. Attempting to reenter critical section of local memory 
manager. 

140 LeaveCrit: local heap is NOT busy 


Internal Windows error. Attempting to leave critical section of local memory 
manager when not already in critical section. 


143 Invalid local heap 
14B Invalid local heap 
15B Invalid local heap 
180 LDREF: Invalid local handle 


A local handle (produced in calls to LocalReAlloc, LocalLock, etc.) is invalid. 


1C0 LocalLock: Object usage count overflow 


LMEM_MOVEABLE or LMEM_DISCARDABLE memory was locked more 
than the limit of 255 times. 


1F0 


1F0 


200 


200 


200 


200 


240 
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LocalFree: freeing locked object 

Local memory was not unlocked before LocalFree was called. 
LocalUnlock: Object usage count underflow 

Local memory was unlocked more times than it was locked. 
gmove_stack usage error 


Internal Windows error using temporary stack. 


Leave_eems_stack error 


Internal Windows error using temporary stack. 


function_name: Invalid global heap,offender_para_reader_header 


Lists the function at which check is occurring (&n = GlobalAlloc, GlobalLock, 
etc.) and generally indicates overwrite of local heap list. 


function_name: Invalid global heap,offender_para_reader_header 


Lists the function where check failed and generally indicates overwrite of local 
heap list. 


If DX is nonzero, DX = offending arena header: 


Code Meaning 

201 Forward links invalid 

202 Backward links invalid 

204 ga_handle points to free handle 

208 Arena points to handle 

280 ga_sig is bad 

If DX is 0: 

Code Meaning 

210 Allocated handles don’t match used handles 
220 Total number of handles don’t match up 
240 Total number of free handles does not match up 


Critical section problems 
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280 edref: invalid handle 


Global handle (produced in calls to GlobalReAlloc, GlobalLock, etc.) is invalid. 
Make sure you: 


RB Have a window procedure for the window. 
= Doa MakeProcInstance call for the window procedure. 


= Export your window procedure. 


2C0 GlobalLock: Object usage count overflow 


GMEM_MOVEABLE or GMEM_DISCARDABLE memory was locked more 
than the limit of 255 times. 


2F0 EMS _GlobalFree: freeing locked object 

Memory was not unlocked before GlobalFree was called. 
2F0 GlobalFree: freeing locked object 

Global memory was not unlocked before GlobalFree was called. 
2F0 GlobalFree: freeing locked object 

Global memory was not unlocked before GlobalF ree was called. 
2F0 | GlobalUnlock: Object usage count underflow 

~ Global memory was unlocked more times than it was locked. 

2F0 GlobalUnWire: Object usage count underflow 

Global memory was unwired more times than it was wired. 
303 PatchStack - invalid BP chain 

Stack frame chain was invalid due to a wild write. 
303 SearchStack - invalid BP chain 

Stack frame chain was invalid due to a wild write. 
401 BOOT: unable to load application 

LoadModule failed for the shell application. 
401 BOOT: Unable to find file pathname 


File not found. 


401 


401 


403 


404 


405 


406 


407 


408 
409 


409 


409 
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BOOT: Invalid .EXE file pathname 


.EXE file format is invalid. 


BOOT: Unable to load pathname 


LoadModule failed for a library loaded during boot time. Pass a far pointer to 
the name of the module that could not be loaded. 


Invalid ordinal reference 


You have linked to a function that does not have an entry point in the version of 
Windows you are running. Check your .DEF file to make sure you are using the 
correct ordinal reference. 


Call to undefined dynlink entry point at entry-point 


A bad import table or wild write occurred over segment relocation table. This 
message is displayed when your application calls the ordinal entry point for a 
driver that no longer contains that ordinal. 


Invalid start procedure 


Bad EXE header. 


Invalid module handle 


Could not obtain EXE header for the specified module handle. 


Invalid relocation record in es,bx 


A wild write destroyed a relocation record. 
Error saving forward reference 


Out of memory loading segment from Module of segment location 


Insufficient memory was available for loading segments. 


1/O error reading segment contents from hModule of segment location 


Unable to read segment due to file open, read, or seek error. 


Segment contents invalid 


Checksum value did not match segment contents when loading a segment. 
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409 Segment contents trashed 
A wild write has occurred on the specified segment. 


Error 409 occurs when a code segment was changed after it was loaded; this is 
usually the result of a wild write. 


Running in the protected-mode version of Windows will cause a general protec- 
tion violation to occur on the code causing the violation. 


Check to make sure your buffers are large enough for the operation. Also, run 
Shaker to see if the problem occurs more frequently. 


410 Error reading relocation records from 


Int 21 function 3F was unable to read off the disk, or the information read is in- 
compatible with the information requested. 


411 Insert disk for specified file 


412 Unable to load non-resident name table 


When attempting to load the nonresident name table, one of the following four 
possible errors occurred: 


= OpenFile failed. 
= Int 21 function 42 (seek) failed. 
= Int 21 function 3F (load seg) failed. 


= The table size is inconsistent with the contents. 


4FF INT 3F handler unable to load segment 


LoadSegment failed. You will receive an “Out of memory loading segment” 
message before you receive this message. 


501 Missing resource table 

502 Bad resource type 

503 Bad resource name 

504 Bad resource file 

505 Unable to read resource from segment 


Int 21 function 3F was unable to read off disk or the information read is incom- 
patible with the information requested. 


505 


600 


700 
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Error loading from resource file filename 


This error has one of these possible causes: 


= The hResInfo parameter of LoadResource is NULL. 
m A wild write has destroyed the module header. 
= A wild write has destroyed the EXE table. 


m= The resource file does not contain the resource requested. 


Atom Manager errors 


A wild write has occurred. 


Input/Output package errors 
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Character Tables 


IBM PC Extended Character Set 


128 
129 
130 
131 
132 
133 
134 
135 
136 
137 
138 
139 
140 
141 
142 
143 


g 144 
ti 145 
é 146 
3 147 
da 148 
5% 149 
3 150 
¢ 151 
é@ 152 
é 153 
e 154 
i 155 
i 156 
i 157 
f° 158 
fi 159 


Indicates that this character is not supported by Windows. 


[os o Oo: o> wm RB Ms 
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160 
161 
162 
163 
164 


165 . 


166 
167 
168 
169 
170 
171 
172 
173 
174 
175 


iw Set Se Gy Oy Ry Os 


O- 16 


ea ed 


a 


>> 


176 
177 
178 
179 
180 
181 
182 
183 
184 
185 
186 
187 
188 
189 
190 
191 


192 
193 
194 
195 
196 
197 
198 
199 
200 
201 
202 
203 
204 
205 
206 
207 


208 
209 
210 
211 
212 
213 
214 
215 
216 
217 
218 
219 
220 
221 
222 
223 


224 
225 
226 
227 
228 
229 
230 
231 
232 
233 
234 
235 
236 
237 
238 
239 
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240 
241 
242 
243 
244 
245 
246 
247 
248 
249 
250 
251 
252 
253 
254 
255 
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ANSI Table 


32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 
52 
53 
54 
55 
56 
57 
58 
59 
60 
61 
62 
63 


Indicates that this character is not supported by Windows. 
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“N own 


? 
a 


64 
65 
66 
67 
68 
69 
70 
71 
72 
73 
74 
715 
76 
77 
78 
79 
80 
81 
82 
83 
84 
85 
86 
87 
88 
89 
90 
91 
92 
93 
94 
95 
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96 

97 

98 

99 
100 
101 
102 
103 
104 
105 
106 
107 
108 
109 
110 
111 
112 
113 
114 
115 
116 
117 
118 
119 
120 
121 
122 
123 
124 
125 
126 
127 
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128 
129 
130 
131 
132 
133 
134 
135 
136 
137 
138 
139 
140 
141 
142 
143 
144 
145 
146 
147 
148 
149 
150 
151 
152 
153 
154 
155 
156 
157 
158 
159 
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193 
194 
195 
196 
197 
198 
199 
200 
201 
202 
203 
204 
205 
206 
207 
208 
209 
210 
211 
212 
213 
214 
215 
216 
217 
218 
219 
220 
221 
222 
223 


rr a aka @ kK & Ot. oS Se tO ome ee eee TP Ps ee OP OD oD Dt oo) Ds 


224 
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Appendix E 
Windows 32-Bit Memory Management DLL 


One of the significant features of the Intel 80386 and 80486 microprocessors is 
the availability of 32-bit registers for the manipulation of code and data. Applica- 
tions written to use these registers can avoid the segmented memory model of ear- 
lier CPUs and instead use a “flat” memory model in which memory is viewed as 
a single, contiguous block. 


Although Microsoft Windows version 3.0 continues to adhere to a segmented 
memory model, Windows does provide a set of functions that allow an applica- 
tion to make use of the 32-bit capabilities of the 80386 and 80486 processors. 
These functions are available to an application through a dynamic-link library 
(DLL) named WINMEM32.DLL. This DLL is supplied as part of the SDK and is 
not part of the retail version of Windows. Consequently, if your application calls 
functions in WINMEM32.DLL, you must include WINMEM32.DLL with your 
application when you distribute it to your application’s end users. 


This appendix introduces the functions contained in WINMEM32.DLL and ex- 
plains how to use these functions in the context of a Windows application. It 
covers the following information: 


= A brief look at some of the differences between a segmented memory model 
and a flat memory model 


= Using WINMEM32.DLL to take advantage of the 32-bit capabilities of the 
80386 and 80486 processors 


= Programming considerations when using these capabilities ina Windows 
application 


= Common approaches for using 32-bit memory in a Windows application 


A directory of the functions supplied by WINMEM32.DLL follows this informa- 
tion. The appendix concludes with several assembly-language code examples il- 
lustrating how to use the DLL’s functions. 


IMPORTANT This appendix assumes that you are thoroughly familiar with the archi- 
tecture and code- and memory-management features of the 80386/80486 processors. This 
appendix does not attempt to explain these features, and assumes that you are familiar with 
the terminology and concepts associated with that architecture. 


Only experienced Windows-application developers with extensive experience writing as- 
sembly-level code should attempt to use these functions in an application. 
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E.1 Segmented and Flat Memory Models 


The 80x86 family of microprocessors implement a segmented memory model in 
which system memory is divided into 64K segments. In the native mode of these 
processors, the address of any byte consists of two 16-bit values: a segment 
address and an offset. In the protected mode of the 80286, 80386, and 80486 pro- 

" cessors, the segment address is replaced by a selector value which the processor 
uses to access the 64K segment. In both modes, memory objects larger than 64K 
will occupy all or part of several segments. An application cannot access these 
objects as though they consist of a single contiguous block simply by in- 
crementing a pointer to the memory. Instead, the application can increment only 
the offset portion of the address, taking care not to exceed the 64K boundary of 
the segment. 


The 80386 processor introduced 32-bit registers that parallel the 16-bit registers 
of older members of the 80x86 family. These registers make it possible for the 
first time to access memory in segments larger than 64K. In fact, the maximum 
segment size is potentially so large (2~“ bytes) that a flat memory model utilizing 
a single segment is now feasible. In this model, an application’s code and/or data 
occupies a single segment. The application can manipulate the 32-bit offset por- 
tion of the memory as though it were a simple pointer. The application can incre- 
ment and decrement the pointer/offset throughout the address space without 
having to deal with multiple segment boundaries. 


To a certain extent, then, the flat memory model most closely resembles the tiny 
memory model in which both code and data occupy a single segment; except, of 
course, that the segment is much larger than the 64K limit imposed by the seg- 
mented memory model. As in the tiny memory model, the beginning of the seg- 
ment of the flat memory model can appear anywhere in memory. In other words, 
the segment-descriptor portion of the address can refer to virtually any location 
in memory. As the application moves through memory, the segment descriptor 
never changes. Only the offset is incremented and decremented to point to differ- 
ent locations in memory. 


As this appendix will note, it is not possible to implement a Windows application 
using an exclusively flat memory model. Windows itself relies on the 16-bit seg- 
mented memory model, and so any application that interacts with Windows must 
implement at least one 16-bit code segment. Despite this limitation, however, it 
is possible for a Windows application to reside largely in one or more 32-bit code 
segments and to use 32-bit data segments. The WINMEM32.DLL library makes 
this possible in a way that ensures the application will cooperate fully with 
Windows and similar platforms. 
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E.2 Using the WINMEMS32.DLL Library 


Although you could directly implement flat memory model code in your 
Windows application, this implementation would necessarily be unique to your 
application. As a result, your application might not run with future versions of 
Windows or with other compatible platforms. 


WINMEM32.DLL supplies a standard method for implementing a flat memory 
model that is guaranteed to run with future versions of Windows and other com- 
patible platforms. It gives your application access to services for allocating, real- 
locating, and freeing 32-bit memory objects; for translating 32-bit pointers to 
16-bit pointers that can be used by Windows and DOS functions; and for aliasing 
a data segment to a code segment so you can execute code loaded into a 32-bit 
segment. 


Your application can load WINMEM32.DLL when Windows is running in real, 
standard, or 386 enhanced mode. However, since the 32-bit registers of the 
80386/80486 processor are available only when Windows is in 386 enhanced 
mode, WINMEM32.DLL is enabled only in that mode. If your application can 
run in real or standard mode, you must design your application so that it can 
access 16-bit memory instead of 32-bit memory in these modes. You can deter- 
mine the mode in which Windows is running by calling the GetWinFlags 
function. . 


WINMEM32.DLL contains eight functions that enable your application to access 
32-bit memory. The following list summarizes each of these functions: 


Function Description 

Global32Alloc Allocates a block of 32-bit memory. 

Global32Realloc Changes the size of a 32-bit memory object. 

Global32Free Frees a 32-bit memory object. 

Global16PointerAlloc Converts a 32-bit pointer to a 16-bit pointer. 

Global16PointerFree Frees a pointer alias created by 
Global16PointerAlloc. 

Global32CodeAlias Creates a code alias for a 32-bit memory ob- 
ject, allowing code in the the object to be 
executed. 

Global32CodeAliasFree Frees a code alias created by 
Global32CodeAlias. 

GetWinMem32Verwsion Returns the version number of the 


WINMEM32.DLL API. 


E-4 Reference — Volume 2 


A directory listing of these functions appears later in this appendix. 


WINMEM372.DLL is a standard Windows DLL, and so your application loads it 
as it would any other DLL. In addition to the DLL, the SDK provides the 
C-language WINMEM32.H include file to declare the functions in your applica- 
tion, and the import library WINMEM32.LIB to allow your application to import 
the functions of the DLL when you link your application. 


The calling convention of the WINMEM32.DLL functions is the same as for 
other Windows functions. The DLL entry points are external FAR PASCAL pro- 
cedures. They preserve SS, BP, DS, SI, and DI, and they return values in AX or 
DX:AX. 


E.3 Considerations for Using 32-Bit Memory 


As previously noted, Windows adheres to the segmented memory model. That is, 
all far pointers are in the form 16:16 consisting of a 16-bit segment address (in 
real mode) or selector (in protected mode), combined with a 16-bit offset within 
the segment. An application using the 32-bit registers of the 80386/80486 proces- 
sor cannot directly call the Windows functions because its far pointers are in the 
form 16:32 and Windows cannot deal with the extra 16 bits in the offset portion 
of the address. 


Because of this conflict, a Windows application cannot reside exclusively in a 32- 
bit segment. It must contain at least one 16-bit “helper” code segment through 
which it interacts with Windows (including WINMEM32.DLL). In other words, 
all calls to Windows functions must be made in the helper code segment. The 
helper segment contains the code that converts the 16:32 pointers in the 32-bit 
segment to the 16:16 pointers used by Windows functions. This segment also per- 
forms the same tasks for the application when the application is making calls to 
DOS, to other DLLs, and to any other code that exclusively uses 16:16 pointers. 


An important limitation on this helper segment is that it must not be discardable. 
If the segment were discarded and a 32-bit segment were to attempt to access the 
segment, an indirect call into the Windows kernel module to reload the segment 

would result. Since the source of this indirect call would not be a 16-bit segment, 
the system might crash. 


Another important consideration is that your application must not assume any- 
thing about the state of the 32-bit registers around 16:16 API calls. For instance, 
the Windows API calls preserve SI and DI, but they presently do not preserve 
ESI and EDI. If the application wants to preserve 32-bit registers around 16:16 
API calls, it must explicitly push and pop the register values around the calls. If 
the 32-bit code segment that calls a Windows function (via the helper segment) 
assumes that ESI and EDI will be preserved when the Windows function returns, 
the helper segment must explicitly save the registers before making the actual 
Windows function call. The helper segment must then restore the registers when 
the Windows function returns. 
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This rule also applies to return values when a 32-bit segment indirectly calls a 
Windows function and the caller expects a 32-bit return value. The helper 
segment must explicitly set the high-order 16 bits of the return value when it 
moves it into the EAX register, as shown in the following examples: 


MOVEZX EAX , AX ; Unsigned return 
MOVESX EAX , AX ; Signed return 


All these considerations apply equally to calls to Windows DLLs, DOS, and | 
other 16-bit APIs. 


E.3.1 The Flat Model Under Windows 


In the Windows environment, system memory is a shared resource which 
Windows manages on behalf of all applications. For this reason, a true flat 
memory model is not possible in the Windows environment. When an applica- 
tion allocates 32-bit memory in Windows, the memory that Windows gives the 
application can be located anywhere in physical memory. The memory to which 
the selector refers is specific to the application and does not include system-wide 
memory locations. In other words, the selector that the application receives does 
not refer to interrupt vector 0. This means that offset 400h for the selector does 
not point to the DOS ROM BIOS data area, for example. 


E.3.2 The Application Stack 


Windows has problems operating in an environment of mixed segment types 
(both 16:16 and 16:32 segments). As a result, the stack selector size must match 
the corresponding code selector size. In other words, when the processor is ex- 
ecuting code in a 16:32 (USE32) code segment, the selector in the SS register 
must also be 16:32. And when code in a 16:16 (USE 16) segment is executing, 
the SS register must contain a 16:16 selector. 


When the 80386/80486 processor is executing on a USE16 stack segment, it uses 
the low-order 16 bits of the ESP register as the SP register. Since only the lower 
16 bits are of use when the processor is executing on a USE16 stack segment, it 
does not control how the upper 16 bits of the ESP register are set. As a result, the 
upper 16 bits are set at random. When an application switches to a USE32 stack 
segment, the ESP register will contain a corrupted pointer unless the high 16 bits 
of ESP are set properly. 


For example, a Windows application has a USE32 code segment and a USE16 
helper segment, but (improperly) only a USE32 stack. When the application calls 
from its USE32 code into the USE16 segment, it stays on its USE32 stack. The 
USE16 code segment calls a Windows function, which changes the selector in 
the SS register to a USE16 selector. Since the stack is now USE16, the upper 16 
bits of the ESP register are set at random. The code that originally switched 
stacks then restores the original selector in SS and, not knowing that it referred to 
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a USE32 stack, restores the 16-bit SP register instead of the full 32 bits of the 
ESP register. As a result, the USE32 stack now has an invalid pointer in the ESP 
register. 


There are a number of ways to deal with this problem. First, an application can 
maintain two separate stacks, one USE16 and the other USE32. Maintaining sepa- 
rate stacks requires you to include extra code —for example, you must copy para- 
meters for stack-calling conventions such as C. Another solution would be to 
maintain one stack but two stack selectors, again one USE16 and the other 
USE32. Both selectors would point to the same USE32 memory. This would re- 
quire the USE32 stack to be restricted to ESP values less than or equal to FFFFh. 


In either case, the USE16 code segment must switch to the USE32 stack immedi- 
ately before calling into a USE32 code segment. When control returns from the 
USE32 code segment to the USE16 code segment, the USE16 segment must im- 
mediately switch back to the USE16 stack before doing anything else. 


Since the problem with stack switching is the corruption of the high 16 bits of 
ESP, a Windows application with 16:32 code must make sure that it sets the high 
16 bits of ESP when it is switching onto the USE372 stack selector. It sets these 
bits by placing the selector into SS, as shown in the following example: 


MOV SS,word ptr [Use32StackSel] 
MOV ESP,dword ptr [Use32StackOffset ] 


MOV SS,word ptr [Use32StackSel ] 
MOVZX ESP,word ptr [Use32StackOffset] 


MOV SS,word ptr [Use32StackSel ] 
MOVZX ESP,SP 


E.3.3 Interrupt-Time Code 


Because Windows is a 16-bit environment, Windows has problems dealing with 
a mixed code-type environment, a 32-bit code segment in a Windows application 
must not contain code that is executed at interrupt time. Also, it must not contain 
data that is accessed at interrupt time. Any code executed at interrupt time must 
be in a USE16 code segment running on a USE16 stack. Data used at interrupt 
time must be USE16 data. This rule also applies to processor exceptions (such as 
the coprocessor exception) since they are handled like interrupts. Note, however, 
that it is acceptable for a 32-bit code segment to access data in a USE16 data 
segment. 
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E.3.4 Programming Languages 


As should be obvious by now, the helper segment has to perform very low-level 
tasks to manage transitions between USE16 and USE32 stacks, and between 
USE16 and USE32 code. For this reason, it is difficult to use a high-level lan- 
guage such as C to write the helper segment code. Even if you were to write the 
helper segment in C, you would have to add assembly-language support for the 
more difficult tasks. In most cases, then, it is easier and more efficient to write 
the entire helper segment in assembly language. 


E.4 Using 32-Bit Memory in a Windows Application 


There are three common uses for 32-bit memory in a Windows application. In in- 
creasing order of complexity, they are: 


= Using 32-bit data objects in 16-bit code 
m= Using 32-bit code and data in a subroutine library 


= Using 32-bit code and data for the main program 


The following sections briefly describe each of these approaches. 


E.4. 1 Using 32-Bit Data Objects 


The simplest use of 32-bit memory is to store data that is used exclusively by 
USE16 code segments. In this case, the application contains no USE32 code 
segments and so does not require a dedicated helper segment. Instead, any (or 
all) of its code segments performs the necessary tasks of allocating, reallocating, 
and freeing the 32-bit memory. If data from the 32-bit memory is to be passed to 
Windows functions or other 16-bit functions, the application’s USE16 code seg- 
ment also performs the aliasing of 32-bit pointers to 16-bit pointers using the 
Global16PointerAlloc function. 
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E.4.2 Using 32-Bit Code and Data in a Subroutine Library 


Using 32-bit memory for code and data can simplify porting an application from 
a 32-bit platforms to the Windows environment when portions of the application 
can be isolated as a subroutine library. This subroutine library serves as a low- 
level engine, but does not call Windows or DOS functions. 


As when the 32-bit memory is used exclusively for data storage, the USE16 code 
segment retains control of the program. Typically, the USE16 segment allocates 
the 32-bit memory, creating one or more objects for code and data. In addition to 
the data-management tasks described in the previous section, the USE16 segment 
also loads the subroutine code into one of the 32-bit segments, fixes up the point- 
ers in the code as required, and creates a code-segment alias to permit the code to 
be executed. The USE16 code segment is responsible for maintaining control of 
the program flow, calling into the USE32 code segment when it requires the low- 
level services of the subroutine library. 


E.4.3 Using 32-Bit Code and Data for the Main Program 


The most complex use of 32-bit memory involves placing the primary control of 
the program in a 32-bit code segment. In this type of application, the USE16 seg- 
ment is reduced exclusively to helper status. During initialization, the USE16 seg- 
ment allocates the 32-bit memory for code and data, loads the code into the 
USE32 segment, creates a code-segment alias for the USE32 segment, and then 
calls the main entry point in the USE32 segment. 


From that point, the USE32 segment takes control of the program, calling into 
the USE16 helper segment only when the application needs to call Windows or 
DOS functions. The USE32 segment continues to control the flow of the pro- 
gram until the application is ready to terminate. Only then does it return control 
to the USE16 segment so the USE16 segment can free the 32-bit memory and 
perform other garbage collection before the application quits. 
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E.5 Functions Directory 


This section describes the functions in WINMEM32.DLL. Most of these func- 
tions return zero to indicate success or a nonzero error-code value to indicate 
failure. The following list describes these error codes. 


Value Meaning 


1 Invalid function. The current Windows mode does not support 
this function. Windows supports the 32-bit memory functions 
only in 386 enhanced mode. 


2 Invalid flags. The wFlags parameter contained invalid bit set- 
tings. The wF lags parameter currently is not used and must be 
set to zero. 

2 Invalid parameter. One of the parameters was invalid. For ex- 


ample, a size parameter was out of range. 


4 Selector not available. There is not enough room in the descrip- 
tor table(s) to allocate the required selector(s). It may be 
necessary to advise the user to close other Windows applications. 


> Insufficient memory. There is not enough memory to satisfy the 
requested allocation or reallocation. 
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GetWinMem32Version 


Syntax 


Return Value 


WORD GetWinMem32Version( ) 


This function returns the API version implemented by the DLL. This is not the version 
number of the DLL itself. 


- This function has no parameters. 


The return value specifies the version of the 32-bit memory API implemented by 
WINMEM32.DLL. The high-order 8 bits contain the major version number, and the 
low-order 8 bits contain the minor version number. The current API version number 
is 1.00 (100h): the major version number is 1, and the minor version number is 0. 


Global16PointerAlloc 


Syntax 


Return Value 


WORD = Global16Pointer Alloc(wSelector, dwOffset, lpBuffer, dwSize, wFlags) 


This function converts a 16:32 pointer into a 16:16 pointer alias that the application can 
pass to a Windows function or other 16:16 functions. 


Parameter Type/Description 

wSelector WORD Specifies the selector of the object for which an alias is to 
be created. This must be the selector returned by a previous call to 
Global32Alloc. 

dwOffset DWORD Specifies the offset of the first byte for which an alias is 


to be created. The offset is from the first byte of the object specified 
by the wSelector parameter. Note that wSelector:dwOffset forms a 
16:32 address of the first byte of the region for which an alias is to be 
created. 


lpBuffer LPDWORD Points to a four-byte location in memory that re- 
ceives the 16:16 pointer alias for the specified region. 


dwSize DWORD Specifies the addressable size in bytes of the region for 
which an alias is to be created. This value must be in the range 1 to 
10000h. 


wFlags WORD Is reserved and must be set to zero. 


The return value is zero if the function was successful. Otherwise, it is one of the error 
codes described at the beginning of this section. 
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Global16PointerFree 


Comments 


When this function returns successfully, the location pointed to by the /pBuffer parameter 
contains a 16:16 pointer to the first byte of the region. This is the same byte to which 
wSelector:dwOffset points. 


The returned selector is a read/write, expand up, small (B bit clear) data descriptor. The 
descriptor DPL and the setting of granularity (the G bit) are at the discretion of the system, 
and so the application should not assume their settings. The descriptor DPL and the selec- 
tor RPL are appropriate for a Windows application. 


NOTE Anapplication must not change the setting of any fields in the descriptor or the selector RPL. 
Doing so can result in a system crash and will prevent the application from running on compatible 
platforms. 


Because of tiling schemes implemented by some systems, the offset portion of the returned 
16:16 pointer is not necessarily zero. 


An application should not assume the size limit of the returned selector. Instead, an applica- 
tion should assume that at least dwSize bytes can be addressed starting at the 16:16 pointer 
created by this function. 


Global16PointerFree 


Syntax 


Return Value 


Comments 


WORD = Globall6PointerFree(wSelector, dwAlias, wFlags) 


This function frees the 16:16 pointer alias previously created by a call to the 
Global16PointerAlloc function. 


Parameter Type/Description 

wSelector WORD _ Specifies the selector of the object for which the alias is to 
be freed. This must be the selector returned by a previous call to 
Global32Alloc. 

dwaAlias DWORD Specifies the 16:16 pointer alias to be freed. This must 


be the alias (including the original offset) returned by a previous call 
to Global16Pointer Alloc. 


wFlags WORD Is reserved and must be set to zero. 


The return value is zero if the function was successful. Otherwise, it is one of the error 
codes described at the beginning of this section. 


An application should free a 16:16 pointer alias as soon as it is no longer needed. Freeing 
the alias releases space in the descriptor table, a limited system resource. 
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Global32Alloc 


Syntax 


Return Value 


Comments 


WORD = Global32Alloc(dwSize, IpSelector, dwMaxSize, wF lags) 


This function allocates a block of memory to be used as a USE32 code or data segment 
and retrieves the selector portion of the 16:32 address of the memory block. The first byte 
of the object is at offset 0 from this selector. 


Parameter Type/Description 

dwSize DWORD _Specifies the initial size in bytes of the block to be allo- 
cated. This value must be in the range of 1 to 4000000h (64 
megabytes). 

IpSelector LPWORD Points to a two-byte location in memory that receives 


the selector portion of the 16:32 address of the allocated object. 


dwMaxSize DWORD _Specifies the maximum size in bytes that the object will 
reach when it is reallocated by the Global32Realloc function. This 
value must be in the range of 1 to 4000000h (64 megabytes). If the 
application will never reallocate this block of memory, the dwMax- 
Size parameter should be set to the same value as the dwSize 
parameter. 


wF lags WORD Is reserved and must be set to zero. 


The return value is zero if the function was successful. Otherwise, it is one of the error 
codes described at the beginning of this section. 


If the Global32Alloc function fails, the value to which /pSelector points is zero. If the 
function succeeds, /pSelector points to the selector of the object. The valid range of offsets 
for the object referenced by this selector is in the range of 0 to (but not including) dwSize. 


The returned selector is a read/write, expand-up, big (B bit set), data descriptor. The 
descriptor DPL and the setting of granularity (the G bit) are at the discretion of the system; 
the application should not assume these settings. Since the system sets the granularity, the 
actual size of the object (and the selector size limit) may be greater than the requested size 
by up to one byte less than 4K. The descriptor DPL and the selector RPL will be appro- 
priate for a Windows application. 


NOTE An application must not change the setting of any fields in the descriptor or the selector RPL. 
Doing so can result in a system crash and will prevent the application from running on compatible 
platforms. 
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Global32CodeAlias 


The allocated object is neither moveable nor discardable, but can be paged. Since page 
locking an object is useful only if the object contains code or data that is used at interrupt 
time, and since 32-bit memory cannot be used at interrupt time, an application should not 
page lock a 32-bit memory object. 


Global32CodeAlias 


Syntax 


Return Value 


Comments 


WORD Global32CodeAlias(wSelector, IpAlias, wFlags) 


This function creates a 16:32 (USE32) code alias selector for a 32-bit memory object pre- 
viously created by the Global32Alloc function. This allows the application to execute 
code contained in the memory object. 


Parameter Type/Description 

wSelector WORD _ Specifies the selector of the object for which an alias is to 
be created. This must be the selector returned by a previous call to 
Global32Alloc. 

IpAlias LPWORD Points to a two-byte location in memory that receives 


the 16:32 code-segment alias selector for the specified object. 


wFlags WORD Is reserved and must be set to zero. 


The return value is zero if the function was successful. Otherwise, it is one of the error 
codes described at the beginning of this section. 


If the function fails, the value pointed to by the /pAlias parameter is zero. If the function is 
successful, /pAlias points to a USE32 code-segment alias for the object specified by the 
wSelector parameter. The first byte of the object is at offset 0 from the selector returned in 
IpAlias. Valid offsets are determined by the size of the object as set by the most recent call 
to the Global32Alloc or Global32Realloc function. 


The returned selector is a read/execute, nonconforming, USE32 (D bit set) code descriptor. 
The descriptor DPL and the setting of granularity (the G bit) are at the discretion of the sys- 
tem, and so the application should not assume their settings. The granularity will be con- 
sistent with the current data selector for the object. The descriptor DPL and the selector 
RPL are appropriate for a Windows application. 


NOTE Anapplication must not change the setting of any fields in the descriptor or the selector RPL. 
Doing so can result in a system crash and will prevent the application from running on compatible 
platforms. 
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An application should not call this function more than once for an object. Depending on 
the system, the function might fail if an application calls it a second time for a given object 
without first calling the Global32CodeAliasFree function for the object. 


Global32CodeAliasFree 
Syntax WORD — Global32CodeAliasFree(wSelector, wAlias, wF lags) 


This function frees the USE32 code selector alias previously created by a call to the 
Global32CodeAlias function. 


Parameter Type/Description 

wSelector WORD _ Specifies the selector of the object for which the alias is to 
be freed. This must be the selector returned by a previous call to 
Global32Alloc. 

WwAlias WORD _ Specifies the USE32 code selector alias to be freed. This 
must be the alias returned by a previous call to Global32CodeAlias. 

wFlags WORD Is reserved and must be set to zero. 

Return Value The return value is zero if the function was successful. Otherwise, it is one of the error 


codes described at the beginning of this section. 


Global32Free | 
Syntax WORD Global32Free(wSelector, wF lags) 


This function frees an object previously allocated by the Global32Alloc function. 


Parameter Type/Description 
wSelector WORD _ Specifies the selector of the object to be freed. This must 
be the selector returned by a previous call to Global32Alloc. 
wFlags WORD Is reserved and must be set to zero. 
Return Value The return value is zero if the function was successful. Otherwise, it is one of the error 


codes described at the beginning of this section. 
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Global32Realloc 


Comments 


This function frees the object itself, as well as all aliases created for the object by the 
32-bit memory API. 


NOTE Before terminating, an application must call this function to free each object allocated by 
Global32Alloc to ensure that all aliases created for the object are freed. 


Global32Realloc 


Syntax 


Return Value 


Comments 


WORD ~ Global32Realloc(wSelector, dwNewSize, wF lags) 


This function changes the size of a 32-bit memory object previously allocated by the 
Global32Alloc function. 


Parameter Type/Description 


wSelector WORD _ Specifies the selector of the object to be changed. This 
must be the selector returned by a previous call to Global32Alloc. 


dwNewSize DWORD _ Specifies the new size in bytes of the object. This value 
must be greater than zero and less than or equal to the size specified 
by the dwMaxSize parameter of the Global32Alloc function call that 
created the object. 


wFlags WORD Is reserved and must be set to zero. 


The return value is zero if the function was successful. Otherwise, it is one of the error 
codes described at the beginning of this section. 


If this function fails, the previous state of the object is unchanged. If the function succeeds, 
it updates the state of the object and the state of all aliases to the object created by the 
32-bit memory API. For this reason, an application must call the Global32Realloc to 
change the size of the object. Using other Windows functions to manipulate the object will 
result in corrupted aliases. . 


This function does not change the selector specified by the wSelector parameter. If this 
function succeeds, the new valid range of offsets for the selector is in the range of 0 to (but 
not including) dwNewSize. 


The system determines the appropriate granularity of the object. As a result, the actual size 
of the object (and the selector size limit) may be greater than the requested size by up to 
one byte less than 4K. 
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. 386p 
mems equ 1 
XLTSt 
include cmacros.inc 


; NOTE that we CANNOT use the normal CMACROS segment macros: 
CreateSeg 
: sBegin 

. sEnd 


; because since we are .386p the default segment type is USE32. Our segments 
; need to be USE16 so we have to declare our segements manually so that the 
; USE16 segment attribute is included. 


. 
Si 


include windows.inc 


.list 


; These equates would normally be in an app specific include file 


error_bad_file EQU O88G1h 
error_wrong_mode EQU Q8882h 


External WINMEM32 Procedures 


externFP GetWinMem32Version 
externFP Global32Alloc 
externFP Global32Realloc 
externFP Global32Free 

externFP Globall6PointerAlloc 
externFP Globall6PointerFree 
externFP Global32CodeAlias 
externFP Global32CodeAliasFree 


; External Windows Procedures 


externFP OpenFile 
externFP GetWinFlags 
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externFP _1l1seek 
externFP _lread 
externFP _lclose 


externFP OemToAnsi 


; MANUAL VERSION OF: createSeg _HELPERCODE,hcode,word,public,CODE 
; NOTE that this segment MUST NOT BE DISCARDABLE, it should be fixed. 
: This is because the segment is called by USE32 code. 


_HELPERCODE segment word public ‘CODE’ usel6 
HELPERCODE ends 


. 
> 


; MANUAL VERSION of the automatic data segment declaration 


_DATA segment word public ‘DATA’ usel6 
_DATA ends 


_DATA segment usel6 


globalD_ AddrOQEMToANSI,@ ; Address of OEMToANSI helper function 
globalD AddrDOSGetFreeSpace,@ ; Address of DOS Get disk Free space 
: helper function 
globalD U32RetVal ,O ; Return code from USE32 call 
globalD Ul6StackAlias,@ ; Alias for the stack 
globalD EntryStackSave,@ ; stack ptr save location 


; This FWORD forms the entry point for the USE32 code 


U32EntryPt LABEL FWORD 


globalD U32EntOff ,@GG19BAGh : Entry assumed at offset 64K 
globalW U32CodeSel ,@ ; CODE alias for the BIG object 
globalW U32DataSel ,@ ; DATA selector for the BIG object 
_DATA ends 


HELPERCODE segment usel6 
assume csS:_HELPERCODE 


KKK KKKK KK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KK KKK KKK KEK KKK KEKE KEK KKKKKKKKKKKKKKKKKEK 
’ 


; SetupCal1USE32 
‘ SetupCal1USE32( fName) 


; Setup and call. into USE32 code 
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; ASSUMPTIONS: 

: The USE32 Image is a @ ORGed 32 bit code image with NO HEADER. 

; The first 64k of the image (offsets @Q@VGRQBG-GOOBFFFFH) is reserved 
‘ for the stack. We put the stack here so that the required stack 
switching (USE32<->USE16) is simply a matter of changing SS. 


The entry point of the USE32 code is assumed to be right after the 
stack at offset Q90819808h in the image. We enter with DS, FS, GS 


; and SS set to the FLAT data segment, and CS set to the flat code 

Ye ss segment. It is the responsibility of the USE32 entry point to set 

; . ES AND PRESERVE IT FOR US. 

: When this code wishes to call the two provided USE16 helper routines, 
, it looks up the call addresses in the AddrOEMTOANSI and 


: AddrDOSGetFreeSpace variables in the _DATA segment. 
; This "loader" code actually needs to pass the selector for the 


: _DATA segment to the USE32 code so that it can access the data 
: segment, or it needs to copy the call addresses into the USE32 
: code/data segment. This detail of the implementation is NOT 


; included in this code. 


s ENTRY: 

; FName - DWORD pointer to file name of USE32 image to load 
; EXIT: 

: AX != @ If an error occurs 

: AX = error code 

; Else 

: AX = @ and U32RetVal contains the return code from the 
; . USE32 code. 

; USES: 

; C Standard 


KKK KKK KKK KKK EK KK KK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKEKKKKKKEKEKEK 
? 


cProc StartupCal1lUSE32,<FAR,PUBLIC>,<si,di> 


ParmD fName 


LocalD fSize ; Size of file 

LocalD Ul16RdAlias ; Alias for reading image 
LocalD FileOff ; Current file offset for read 
LocalW fHand ; File handle 


LocalV OpnBuf,<SIZE OPENSTRUC> ; Open file struct for openfile call 


cBegin 
assume ds:_DATA 
assume es:nothing 
assume ss:_DATA 
; First check if we are running in enhanced mode 


; NOTE THAT SINCE WE DO NOT KNOW AS YET WHAT MODE WE ARE IN WE NEED 


. 
’ 
. 
’ 
. 
’ 
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TO AVOID USING 386 SPECIFIC INSTRUCTIONS 


cCall GetWinFlags 


and ax,WF_PMODE + WF_ENHANCED 

cmp ax,WF_PMODE + WF_ENHANCED 

je short OKtoLoad ; MUST BE SHORT 
mov ax,error_wrong_mode 

jmp Donel 


We now know we are in the proper mode and that 386 instructions 
are now OK. 


OKtoLoad: 


. 
’ 
’ 


; Set up the addresses for the USE32 code to call the helper routines 


mov ax,cs 

mOv word ptr (CAddrOEMToANSI+2],ax 

mov word ptr [AddrOEMToANSI],offset _HELPERCODE:U320EMtoANSI 

mov word ptr [AddrDOSGetFreeSpacet+2],ax 

mov word ptr [AddrDOSGetFreeSpace],offset _HELPERCODE:U32GetDskFree 


Open the file 


lea bx, OpnBuf 
regptr ssbx,ss,bx 
cCall OpenFile,<fName,ssbx,QF_READ> 


cmp. ax,-l - 3 Did we find it? 
je DonelFlerr ; No, file error 
mov fHand,ax ; Save file handle 


Get file size 


cCal] _llseek,<fHand,@,@,2> 


shl edx,16 

mov dx,ax 

inc edx 

jz DonelFlErr ; seek failed, file error 

dec edx 

mov fSize,edx 

cmp edx ,18888h ; Image is at least 64k? 

jbe DonelFlErr ; No, size is too small, file error 


Move file pointer back to start of file for read 
cCal] _llseek,<fHand,@,0,> 
Allocate big USE32 object 


mov si,dataOffset U32DataSel 
regptr Selpt,ds,si 
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cCall Global32Alloc,<fSize,Selpt,fSize,@> 
or ax,ax ; Worked? 
jnz FcloseEr ; No, return WINMEM32 error code 


; Allocate USE16 stack alias for first 64K of object 


mov si,dataOffset Ul6StackAlias 

regptr Alipt,ds,si 

mov €cx ,9BB19BWBBh ; 64K 

cCal] Global1l6PointerAlloc,<{U32DataSel],8,0,Alipt,ecx,@> 

or ax,ax ; Worked? 

jnz AliasErrF3 ; No, return WINMEM32 error code 


; Allocate USE32 code alias 


mov si,dataOffset U32CodeSel 

regptr Alipt,ds,si 

cCal] Global32CodeAlias,<[U32DataSel],Alipt,@> 

or ax,ax ; Worked? 

jnz AliasErrF2 ; No, return WINMEM32 error code 


; Now read in the image. We will do this in 32K hunks. 


. 
, 


mov FileOff,@ ; Starting at file offset @ 
ReadLp: 

mov eCX , OBOLBBRBGh ; 32k 

cmp ecx,fSize 

jbe short Read32k 

mov ecx,fSize 


Read32k: 


; Make a USE16 alias for this region of the object 
push CX 
lea si,U1L6RdAlias 
regptr Alipt,ss,si 
cCal] Globall6PointerAlloc,<(U32DataSel],FileOff,Alipt,ecx,@> 


pop CX 

or ax,ax 

jnz short AliasErrFl 

push eCx 

cCall _lread,<fHand,U1l6RdAlias,cx> 
push ax a 
cCall Globall6PointerFree,<CU32DataSel],U16RdAlias ,@> 
pop ax 

pop @CX 

inc ax 

jz short FlRdErr 

dec ax 

cmp ax,Cx 

jne short FlRdErr 


add FileOff,ecx 


sub 
ja 
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fSize,ecx 
short ReadLp 


; We are now ready to set up and call into the USE32 code 


we we we we we 


mov 
mov 
mov 
push 
pop 


Save the current stack so we can switch to the USE32 stack 


NOTE CAREFULLY THAT THIS MAKES THIS ROUTINE NON-REENTRANT 
SINCE IT SAVES THE CURRENT SS:SP IN A STATIC MEMORY LOCATION. 


word ptr [LEntryStackSave],sp 
word ptr LEntryStackSave+2],ss 
ax, [U32DataSel J 

ds 

es 


assume es:_DATA 


; Set up all the segs, and call into USE32 


; NOTE that we just leave the file open across the call. 


mov: ds ,ax 
assume ds:nothing 
mov fS,ax 
MOV gs,ax 
mov SS,aXx 
assume ss:nothing 
mov esp, QOOBFFFCh 
call [U32EntryPt] 


; Recover DS and stack. 


mov 
mov 


bx,es 
ds,bx 


assume ds:_DATA 


mov 


ss,word ptr [EntryStackSavet2] 


assume ss:_DATA 


mov 


. 
’ 


sp,word ptr [EntryStackSave] 


; Set success return and clean up. 


; 
mov 
xor 


jmp 


FIRdErr: 


mov 


AliaserrFl: 


[U32RetVal],eax 
ax,ax ; Return success 
short AliasErrFl 


ax,error_bad_file 


; Free USE32 code alias 


. 
’ 


push 


ax ; Save error code 
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cCall Global32CodeAliasFree,<[U32DataSel ],[U32CodeSel] ,@> 
pop ax 
AliasErrFe: 


; Free USE16 stack alias 


push ax ; Save error code 
cCall Global16PointerFree,<[U32DataSel],[U16StackAlias],@> 
pop ax 


AliasErrF3: 


; Free the object 


push ax ; Save error code 
cCall Global32Free,<{U32DataSel],@> 
pop ax 

FcloseEr: 


; Close the file 


push ax ; Save error code 
cCall _Iclose,<fHand> 
pop ax 
jmp short Donel 
DonelFleErr: 
mov ax,error_bad_file 
Donel: 
cEnd 


KKK KKK KKK KKK KKK KKK KEK KK KKK KKK KKK KKK KKK KKK KKK KEKE KKK KEK KKK KKK KE KKK KKEKKKEKKKKKEE 
’ 


; U32Z0EMtoANSI - Call OemToANSI from USE32 segment 


‘ Assumes PASCAL calling convention 


; ENTRY: 
; ' U320EMtoANSI(1pOemStr,1pAnsiStr) 
; NOTE that these pointer arguments are NOT really LPSTRs. They 
: are near pointers into the USE32 data object (implied segment 
: is U32DataSel ) 
; EXIT: 
; EAX is return code 
USES: 


32 bit C Standard 


we we we we we 


eC KKKKKKKKEK KKK KKK KKK KEK KKK KK KEK KKK KKK KKK KKK KKK KKK KKK KEK KKK KKK KKK KKK KKKEKKKEKKKKKER 


PUBLIC U320EMtoANSI 
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U320EMtoANSI proc far 
assume ds:nothing 
assume es:nothing 
assume ss:nothing 


; First switch to the USE16 stack 


mov cx,ds ; Save entry DS in cx till we get the stack switched 
mov ax,SEG _DATA 
mov ds,ax 
assume ds:_DATA 
mov ss,word ptr [Ul6StackAliast+2] 
push e@CX ; Entry DS, as DWORD to keep stack aligned 
push ebp 
mov bp,sp 


; Frame now looks like this: 

; dword ptr [bp + 20] --> First arg to OEMToANSI JIpOemStr (actually a 32 
bit near pointer) 

: dword ptr [bp + 16] --> Second arg to OEMToANSI IpAnsiStr (actually a 32 
bit near pointer) 


: dword ptr [bp + 12] --> Return CS 
: dword ptr [bp + 8] --> Return EIP 
: dword ptr [bp + 4] --> Entry DS pushed as DWORD 
; dword ptr [bp + 9] --> Entry EBP 
lpOemStr equ dword ptr [bpt+20] 
TpAnsiStr equ dword ptr [bp+1l6] 
sub sp,8 ; Need two LPSTRs for the aliases 
AlsOemStr equ dword ptr [bp-4] ; Alias for ]pOemStr 
AlsAnsiStr equ dword ptr [bp-8] ; Alias for lpAnsiStr 
push esi 
push edi 
push ebx 
push es ; Preserve "flat" ES, FS, GS 
push fs 
push gs 


; There is a ?, how BIG is ]pQemStr? Need to know this to set the 

: size of the alias(s). What we will do is "cheat". We will set 

; the size to 64k (or size to end of USE32 object, whichever is 

: smaller). NOTE that this assumes that the string is <= 64K which 
: is a reasonable assumption since we can't alias something larger 
; than that anyway. 


1s ~ eax,dword ptr [U32DataSel] ; Get limit of USE32 object 
inc eax ; Limit -> size 
mov edx,@ax 
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sub eax, |pOemStr ; Number of bytes to end of USE32 object 

ae SkipCall ; Bad string ptr 

sub edx,]pAnsiStr ; Number of bytes to end of USE32 object 

jc short SkipCall ; Bad string ptr 

cmp , eax,edx 

jbe short UseSrcLim 

mov eax ,edx ; IpAnsiStr is closer to end of object 
UseSrcLim: 

mov ecx ,O0018800Gh ; 64k 

cmp eCX,e@ax 

jbe short Use64k 

mov ecx,e@ax ; Limited by size to end of object 


Use64k: 


; Create Alias for 1pOemStr 
push e€CX 
lea bx ,AlsOemStr 
regptr AlsPt,ss,bx 


cCall Globall6PointerAlloc,<{CU32DataSel],]pOemStr,AlsPt,ecx,@> 


pop CX 
or ax ,ax 
jnz short SkipCal] 


; Create Alias for lpAnsiStr 
lea bx,AlsAnsiStr 
cCall Globall6PointerAlloc,<{U32DataSel],1pAnsiStr,AlsPt,ecx,@> 


or ax,ax 
jnz short FreeQemAls 


; Call OemToAnsi 

cCall OemToAnsi ,<AlsOemStr ,AlsAnsiStr> 
a Free the aliases 

push ax ; Save RET code 


cCall Globall6PointerFree,<{U32DataSel],AlsAnsiStr,@> 


pop ax ; Restore RET code 
FreeQemAls: 
push ax ; Save RET code 


cCal] Globall6PointerFree,<[U32DataSel],AlsOemStr,@> 


pop ax ; Restore RET code 
SkipCall: 
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pop gs 

pop fs 

pop es 

pop ebx 

pop edi 

pop esi 

add sp,8 

pop ebp 

pop Cx ; Entry DS in CX 


; Sign extend the return to make it 32 bit 
MOVSX  @AaX,aX 


; Switch back to the USE32 stack MAKING SURE TO SET HIGH 16 BITS OF ESP. 


mov ss,CU32DataSel J 
mMOVZX esp,sp 
MOV ds,cx 
assume ds:nothing 
db 66h ; USE32 override on far ret so it returns to EIP 
ret (2 * 4) 


U320EMtoANSI endp 


CKKKKEKKEKKKKEKKKKKKEKKKEKE KR KEK KEKE KK KEK KK KKK EKER KKK KKK KEKE KEKE KKEKKKEKEKKRKEKKKEKKKKKKKKK 


; U32GetDskFree - Issue DOS call to get disk free space 
. Assumes PASCAL calling convention 


; ENTRY: 
: U32GetDskFree(drvnum) 


> EXIT: 
: EAX = Disk free space in bytes 
: EAX == QOFFFFFFFFh if error 


> USES: 
: 32 bit C Standard 


’ 
CKKKEKKEKKEKKEKEKKEKKKKKKKKKKK KKK KEK KKK KKK KK KKKKEKE KEKE KKK KKEKEKRKEKKKEKKEKRKEKKKEKKKKKKKKKKKK 
’ 


PUBLIC U32GetDskFree 


U32GetDskFree proc far 
assume ds:nothing 
assume es:nothing 
assume ss:nothing 


; First switch to the USE16 stack 
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mov cx,ds ; Save entry DS in cx till we get the stack switched 
mov ax,SEG _DATA 
mov ds,ax 
assume ds:_DATA 
mov ss,word ptr [Ul6StackAliast2] 
push eCX ; Entry DS, as DWORD to keep stack aligned 
push ebp 
mov bp,sp 


s Frame now looks like this: 


16] --> Drive # argument (@ = default, A=1...) 
12): --> Return CS 


;  dword ptr [bp 
; dword ptr [bp 


++ +44 
foe) 
Ly 
| 
| 
Vv 


; dword ptr [bp Return EIP 
; dword ptr [bp + 4] --> Entry DS pushed as DWORD 
; dword ptr [bp + @] ac (EnGry. -EBP 
ArgDrv equ dword ptr [bpt1l6] 
push esi 
push edi 
push ebx : 
push es ; Preserve "flat" ES, FS, GS 
push fs 
push gs 
mov edx,ArgDrv ; Drive # to DL 
mov ah,36h 
int 21h ; Make DOS call 


MOVSX €ax,ax ; Sign extend AX for error 


cmp ax, @FFFFh ; Error? 

je short BadDrv ; Yes, return OFFFFFFFFh 

mMOvzZxX eax,ax ; Convert sectors/cluster to 32 bit 

mMovzx ebx,bx ; Convert Available clusters to 32 bit 

movzx €CX,CX ; Convert bytes/sector to 32 bit 

mul €CX ; EAX = sectors/cluster * bytes/sector = 
: bytes/cluster 

mul ebx ; EAX = bytes/cluster * Available clusters = 
: free bytes 

BadDrv: 

pop gs 

pup TS 

pop es ‘ 

pop ebx 

pop edi 

pop esi 

pop ebp 

pop ecx sCEntry DS: “1n- Cx 


; Switch back to the USE32 stack MAKING SURE TO SET HIGH 16 BITS OF ESP. 


mov ss,LU32DataSel ] 
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movzx  eSp,sp 


mov ds,cx 

assume ds:nothing 
db 66h ; USE32 override on far ret so it returns to EIP 
ret (1 * 4) 


U32GetDskFree endp 
HELPERCODE ends 


end 
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Special Characters 


\a. See Escape character 
_ _Acrtused symbol, (vol. 2) 13-5 
& (ampersand) 

use in dialog control statement, (vol. 2) 8-21 to 8-25, 
8-27 to 8-29 

use in MENUITEM statement, (vol. 2) 8-10 
BACKSPACE key, (vol. 2) 8-36 
Bold text, as document convention, (vol. 1) xxiv 
4 (caret), (vol. 2) 8-7, 8-8 
?CHKSTK, Cmacro, (vol. 2) 13-6 
CONTROL key, (vol. 2) 8-8 
{ } (curly braces), as document convention, (vol. 1) xxv 
#define directive, resource compiler, (vol. 2) 8-48 
[[ ] (double brackets), as document convention, (vol. 1) 
XXV 
... (ellipses), as document convention, (vol. 1) xxiv 
#endif directive, resource compiler, (vol. 2) 8-51 
#if directive, resource compiler, (vol. 2) 8-49 to 8-50 
#ifdef directive, resource compiler, (vol. 2) 8-48 
#ifndef directive, resource compiler, (vol. 2) 8-49 
#include directive, resource compiler, (vol. 2) 8-47 
Italic text, as document convention, (vol. 1) xxiv 
_Iclose function, (vol. 1) 3-14, 4-271 
_Icreat function, (vol. 1) 3-14, 4-271 
_llseek function, (vol. 1) 3-14, 4-274 
_lopen function, (vol. 1) 3-14, 4-294 to 4-295 
_lread function, (vol. 1) 3-14, 4-297 
_Iwrite function, (vol. 1) 3-14, 4-300 to 4-301 
Monospaced type, as document convention, (vol. 1) 
XXiv, (vol. 2) ix 
() (parentheses), as document convention, (vol. 1) xxiv 
?PLM option 
calling convention, defined, (vol. 2) 13-8 
Cmacro, (vol. 2) 13-3 to 13-4 
(quotation marks), as document convention, (vol. 1) 
XXV 
SHIFT key, (vol. 2) 8-8 
\t. See Escape character 
TAB key, (vol. 2) 8-17 
#undef directive, resource compiler, (vol. 2) 8-48 
| (vertical bar), as document convention, (vol. 1) xxvx 
?WIN option, Cmacro, (vol. 2) 13-4 
32-bit memory management, (vol. 2) E-1 to E-8 


A 


ABORTDOC printer escape, (vol. 2) 12-2 
Absolute symbol, Cmacro, (vol. 2) 13-5 
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Accelerators 
See also ACCELERATORS resource statement 
loading or translating, (vol. 1) 1-4 
with dialog boxes, (vol. 1) 1-52 
ACCELERATORS resource statement, (vol. 2) 8-7 
AccessResource function, (vol. 1) 3-7, 4-2 
AddAtom function, (vol. 1) 3-9, 4-2 
AddFontResource function, (vol. 1) 2-28, 4-3 
Addition (+) operator, (vol. 2) 8-21 to 8-26, 8-28 to 8-33 
AdjustWindowRect function, (vol. 1) 1-7, 4-3 
AdjustWindowRectEx function, (vol. 1) 1-7, 4-4 
Aligning brushes, (vol. 1) 1-39 
Alignment, segment, (vol. 2) 14-5 
AllocDStoCSAlias function, (vol. 1) 3-5, 4-5 
AllocResource function, (vol. 1) 3-7, 4-5 
AllocSelector function, (vol. 1) 3-5, 4-6 
ALTERNATE filling mode, (vol. 1) 4-58, 4-389 
ALTERNATE polygon-filling mode, (vol. 1) 4-58, 
4-197, 4-389 
Ampersand (&), adding a mnemonic with, (vol. 2) 8-10, 
8-21 to 8-25, 8-27 to 8-29 
AnimatePalette function, (vol. 1) 2-10, 4-7 
ANSI table, (vol. 2) D-2 
ANSI_FIXED_FONT stock object, (vol. 1) 4-207 
ANSI_VAR_FONT stock object, (vol. 1) 4-207 
AnsiLower function, (vol. 1) 3-8, 4-7 
AnsiLowerBuff function, (vol. 1) 3-8, 4-8 
AnsiNext function, (vol. 1) 3-8, 4-8 
AnsiPrev function, (vol. 1) 3-8, 4-9 
AnsiToOem function, (vol. 1) 3-8, 4-9 
AnsiToOemBvuff function, (vol. 1) 3-8, 4-10 
AnsiUpper function, (vol. 1) 3-8, 4-10 
AnsiUpperBuff function, (vol. 1) 3-8, 4-11 
AnyPopup function, (vol. 1) 1-57, 4-11 
AppendMenu function, (vol. 1) 1-26, 1-56, 4-11 to 4-13, 
4-54, 4-59, 4-211, 6-106 
Application, assembly language, (vol. 2) 13-1 
Arc function, (vol. 1) 2-22, 4-14 
Arg macro 
arguments, position of, (vol. 2) 14-3 
cCall, use with, (vol. 2) 14-2 
Cmacro, (vol. 2) 14-2 
Argument, cCall list specification, (vol. 2) 14-3 
Argument, macro. See Argument, cCall list specification 
ArrangelIconic Windows function, (vol. 1) 1-28, 4-15 
ASCII character, use with ACCELERATORS statement, 
(vol. 2) 8-7 
ASPECTX device capability, (vol. 1) 4-167 
ASPECTXY device capability, (vol. 1) 4-167 
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ASPECTY device capability, (vol. 1) 4-167 
Assembly language 
calling conventions, (vol. 2) 13-3 
checking the stack, (vol. 2) 13-5 
creating, (vol. 2) 13-1 to 13-2 
creating application entry point, (vol. 2) 13-5 
declaring callback functions, (vol. 2) 13-5 
enabling stack checking, (vol. 2) 13-6 
error macros, (vol. 2) 13-9 
macros, (vol. 2) 13-1 
memory options, specifying, (vol. 2) 13-2 
prolog/epilog option, enabling, (vol. 2) 13-4 
segment macros, (vol. 2) 13-6 to 13-7 
special definition macros, (vol. 2) 13-8 
storage-allocation macros, (vol. 2) 13-7 
Assembly-language macro, Cmacro, (vol. 2) 13-6, 14-1 
assumes macro, Cmacro, (vol. 2) 14-2, 14-6 


B 


Background 
brush, class background, (vol. 1) 1-13 
color, default, (vol. 1) 1-33 
mode, default, (vol. 1) 1-33 
BANDINFO printer escape, (vol. 2) 12-2 to 12-4 
- BEGIN_PATH printer escape, (vol. 2) 12-5 
BeginDeferWindowPos function, (vol. 1) 1-28, 4-16 
BeginPaint function, (vol. 1) 1-31, 4-16 
BITBLT, example Cmacros function, (vol. 2) 13-9 to 
13-10 
BitBlt function 
and color palettes, (vol. 1) 2-13 
described, (vol. 1) 2-25, 4-17 to 4-19 
Bitmap 
file format, (vol. 2) 7-10 
memory, setting bits in, (vol. 1) 4-375 
mouse cursor shape, (vol. 2) 8-2 
resource, (vol. 2) 8-2 
BITMAP data structure, (vol. 2) 7-6 
Bitmap, device-dependent, getting device-independent 
bits from, (vol. 1) 4-171 
Bitmap, device-independent 
BITMAPCOREHEADER data structure, (vol. 2) 7-8 
BITMAPCOREINFO data structure, (vol. 2) 7-9 
BITMAPINFO data structure, (vol. 2) 7-11 
BITMAPINFOHEADER data structure, (vol. 2) 7-14 
color, (vol. 2) 7-58 to 7-59 
creating, (vol. 1) 4-44 
described, (vol. 2) 7-9, 7-11 to 7-12 
displaying, (vol. 1) 4-377 
file format, (vol. 2) 9-1 
retrieving bits, (vol. 1) 4-171 
setting on display surface, (vol. 1) 4-377 


Bitmap functions 

device independent, list of, (vol. 1) 2-26 to 2-27 

list of, (vol. 2) 2-25 to 2-26 
BITMAP resource-compiler key word, (vol. 2) 8-2 
BITMAPCOREHEADER data structure, (vol. 2) 7-7, 7-9 
BITMAPCOREINFO 

See also RGBTRIPLE 

data structure, (vol. 2) 7-8 to 7-9 
BITMAPFILEHEADER data structure, (vol. 2) 7-10 
BITMAPINFO 

See also RGBQUAD 

data structure, (vol. 1) 4-45, 4-171, 4-376, (vol. 2) 7-10 to 
7-11, 7-14 
BITMAPINFOHEADER data structure, (vol. 1) 4-44 to 
4-45, (vol. 2) 7-11 to 7-15 
BITSPIXEL device capability, (vol. 1) 4-167 
BLACK_BRUSH stock object, (vol. 1) 4-207 
BLACK_PEN stock object, (vol. 1) 4-207 
BLACKNESS raster-operation code, (vol. 1) 4-19 
BLACKONWHITE stretching mode, (vol. 1) 4-399 
BM_GETCHECK message, (vol. 1) 5-9, 6-4 
BM_GETSTATE message, (vol. 1) 5-9, 6-4 
BM_SETCHECK message, (vol. 1) 5-9, 6-4 
BM_SETSTATE message, (vol. 1) 5-9, 6-5 
BM_SETSTYLE message, (vol. 1) 5-9, 6-5 to 6-6 
BN_CLICKED message, (vol. 1) 5-15, 6-7 
BN_DOUBLECLICKED message, (vol. 1) 5-15, 6-7 
BOOL data type, (vol. 2) 7-1 
Border, window, (vol. 2) 8-16 
Braces, curly ({ }), as document convention, (vol. 1) xxv 
Brackets, angle (< >), (vol. 2) 14-5 
Brackets, double ({[ ]]), as document convention, (vol. 1) 
XXV 
BringWindowToTop function, (vol. 1) 1-28, 4-20 
Brush 

alignment, (vol. 1) 1-39 

creating, (vol. 1) 4-35, (vol. 2) 7-39 

default, (vol. 1) 1-33 

origin, default, (vol. 1) 1-33 
BS_3STATE control style, (vol. 1) 4-69, 6-6, (vol. 2) 8-38 
BS_AUTO3STATE control style, (vol. 1) 4-68, 6-6, (vol. 
2) 8-38 


- BS_AUTOCHECKBOxX control style, (vol. 1) 4-68, 6-6, 


(vol. 2) 8-37 

BS_AUTORADIOBUTTON control style, (vol. 1) 6-6, 
(vol. 2) 8-37 

BS_CHECKBOX control style, (vol. 1) 4-68, 6-6, (vol. 
2) 8-37 ; 
BS_DEFPUSHBUTTON control style, (vol. 1) 4-68, 6-6, 
(vol. 2) 8-37 

BS_GROUPBOxX control style, (vol. 1) 4-68, 6-6, (vol. 
2) 8-38 

BS_HATCHED brush style, (vol. 2) 7-39 
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BS_HOLLOW brush style, (vol. 2) 7-39 
BS_LEFTTEXT control style, (vol. 1) 4-68, 6-6, (vol. 2) 
8-37 
BS_OWNERDRAW control style, (vol. 1) 4-69, 6-6 to 
6-7, (vol. 2) 8-38 
BS_PATTERN brush style, (vol. 2) 7-39 
BS_PUSHBUTTON control style, (vol. 1) 4-69, 6-6, 
(vol. 2) 8-37 
BS_RADIOBUTTON control style, (vol. 1) 4-69, 6-6 to 
6-7, (vol. 2) 8-37 
BS_SOLID brush style, (vol. 2) 7-39 
BuildCommDCB function, (vol. 1) 3-11, 4-20 
BUTTON control class 

control styles, (vol. 2) 8-24, 8-27, 8-29 to 8-30, 8-37 

described, (vol. 1) 4-64, 4-68, (vol. 2) 8-23, 8-25, 8-27, 
8-35 
Button notification codes, (vol. 1) 5-15 
Button, owner-draw, (vol. 1) 1-50, (vol. 2) 7-36, 7-48 
BYTE data type, (vol. 2) 7-1 
BYTE, segment alignment type, (vol. 2) 14-5 


C 


C language, library, (vol. 2) 13-5 
Cache, display-context, (vol. 1) 1-36 
Call macros, Cmacro, (vol. 2) 13-8 
Callback functions, (vol. 2) 13-5 
Calling convention 

Cmacro, (vol. 2) 13-3 

high-level language, (vol. 2) 13-3 

Pascal, (vol. 2) 13-3 
CallMsgFilter function, (vol. 1) 1-63, 4-21 
CallWindowProc function, (vol. 1) 1-2, 1-16, 4-21 
Capital letters, small, as document convention, (vol. 1) 
XXV, (vol. 2) x 
CAPTION resource statement, (vol. 2) 8-18 
Caret (“) 

creating and displaying, (vol. 1) 1-61 

functions, (vol. 1) 1-60 

in ACCELERATORS statement, (vol. 2) 8-7 to 8-8 

sharing, (vol. 1) 1-61 
Carriage-retumn character, (vol. 2) 8-40 
Catch function, (vol. 1) 3-6, 4-22 
CB_ADDSTRING message, (vol. 1) 5-13, 6-8, 6-10 to 
6-11, 6-14, (vol. 2) 7-38, 7-49 
CB_DELETESTRING message, (vol. 1) 5-13, 6-8, 6-57 
CB_DIR message, (vol. 1) 5-13, 6-9 
CB_FINDSTRING message , (vol. 1) 5-13, 6-9 
CB_GETCOUNT message, (vol. 1) 5-14, 6-10 
CB_GETCURSEL message, (vol. 1) 5-14, 6-10 
CB_GETEDITSEL message, (vol. 1) 5-14, 6-10 
CB_GETITEMDATA message, (vol. 1) 5-14, 6-11 
CB_GETLBTEXT message, (vol. 1) 5-14, 6-11 


CB_GETLBTEXTLEN message, (vol. 1) 5-14, 6-12 
CB_INSERTSTRING message, (vol. 1) 5-14, 6-8, 6-10 
to 6-12, 6-14, (vol. 2) 7-38, 7-49 
CB_LIMITTEXT message, (vol. 1) 5-14, 6-12 
CB_RESETCONTENT message, (vol. 1) 5-14, 6-13, 6-57 
CB_SELECTSTRING message, (vol. 1) 5-14, 6-13 
CB_SETCURSEL message, (vol. 1) 5-14, 6-14 © 
CB_SETEDITSEL message, (vol. 1) 5-14, 6-14 
CB_SETITEMDATA message, (vol. 1) 5-14, 6-11, 6-15 
CB_SHOWDROPDOWN message, (vol. 1) 5-14, 6-15 
cBegin macro, Cmacro, (vol. 2) 14-2 
CBN_DBLCLK message, (vol. 1) 5-17, 6-15 
CBN_DROPDOWN message, (vol. 1) 5-17, 6-16 
CBN_EDITCHANGE message, (vol. 1) 5-17, 6-16 
CBN_EDITUPDATE message, (vol. 1) 5-17, 6-16 
CBN_ERRSPACE message, (vol. 1) 5-17, 6-17 
CBN_KILLFOCUS message, (vol. 1) 5-17, 6-17 
CBN_SELCHANGE message, (vol. 1) 5-17, 6-17 
CBN_SETFOCUS message, (vol. 1) 5-17, 6-18 
CBS_AUTOHSCROLL control style, (vol. 2) 8-39 
CBS_DROPDOWN control style, (vol. 2) 8-38 
CBS__DROPDOWNLIST control style, (vol. 2) 8-38 
CBS_HASSTRINGS control style, (vol. 1) 4-69, 6-8, 
6-10 to 6-12, 6-14, (vol. 2) 8-39 
CBS_OEMCONVERT control style, (vol. 1) 4-70, (vol. 
2) 8-39 
CBS_OWNERDRAWFIXED control style, (vol. 1) 4-70, 
(vol. 2) 8-38 
CBS_OWNERDRAWVARIABLE control style, (vol. 1) 
4-70, (vol. 2) 8-38 
CBS_SIMPLE control style, (vol. 2) 8-38 
CBS_SORT control style, (vol. 2) 8-39 
cCall macro 

Arg macro, use with, (vol. 2) 14-2 

Cmacro, (vol. 2) 13-8 

FarPtr macro, use with, (vol. 2) 14-9 

Save macro, use with, (vol. 2) 14-14 
CE_BREAK communication error code, (vol. 1) 4-161 
CE_CTSTO communication error code, (vol. 1) 4-161 
CE_DNS communication error code, (vol. 1) 4-161 
CE_DSRTO communication error code, (vol. 1) 4-161 
CE_FRAME communication error code, (vol. 1) 4-161 
CE_IOE communication error code, (vol. 1) 4-161 
CE_MODE communication error code, (vol. 1) 4-161 
CE_OOP communication error code, (vol. 1) 4-161 


*CE_OVERRUN communication error code, (vol. 1) 


4-161 

CE_PTO communication error code, (vol. 1) 4-161 
CE_RLSDTO communication error code, (vol. 1) 4-161 
CE_RXOVER communication error code, (vol. 1) 4-162 
CE_RXPARITY communication error code, (vol. 1) 
4-162 

CE_TXFULL communication error code, (vol. 1) 4-162 
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cEnd macro, Cmacro, (vol. 2) 14-3 
CF_BITMAP clipboard format , (vol. 1) 4-370 
CF_DIB clipboard format, (vol. 1) 4-370 
CF_DIF clipboard format, (vol. 1) 4-370 
CF_DSPBITMAP clipboard format, (vol. 1) 4-370 
CF_DSPMETAFILEPICT clipboard format, (vol. 1) 
4-370 
CF_DSPTEXT clipboard format, (vol. 1) 4-370 
CF_METAFILEPICT clipboard format, (vol. 1) 4-370 
CF_OEMTEXT clipboard format, (vol. 1) 4-371 
CF_OWNERDISPLAY clipboard format, (vol. 1) 4-371 
CF_PALETTE clipboard format, (vol. 1) 4-157, 4-371 
CF_SYLK clipboard format, (vol. 1) 4-371 
CF_TEXT clipboard format, (vol. 1) 4-371 
CF_TIFF clipboard format, (vol. 1) 4-371 
ChangeClipboardChain function, (vol. 1) 1-59, 4-23 
ChangeMenu. See AppendMenu; DeleteMenu; 
InsertMenu; ModifyMenu; RemoveMenu 
ChangeMenu function, (vol. 1) 4-23 
ChangeSelector function, (vol. 1) 3-5, 4-24 
char data type, (vol. 2) 7-1 
Character 

determining if alphabetic, (vol. 1) 4-263 

determining if alphanumeric, (vol. 1) 4-264 

determining if lowercase, (vol. 1) 4-264 

determining if uppercase, (vol. 1) 4-264 

escape 

\a, (vol. 2) 8-10 
\t, (vol. 2) 8-10 

Character cell, (vol. 1) 2-31 
Character tables, (vol. 2) D-1 to D-2 
CHECKBOX resource statement 

described, (vol. 2) 8-23 to 8-24 

DIALOG resource statement, (vol. 2) 8-20 
CheckDlgButton function, (vol. 1) 1-43, 4-24 
CHECKED option 

MENUITEM resource statement, (vol. 2) 8-10 

POPUP resource statement, (vol. 2) 8-12 
Checkmark 

custom, (vol. 1) 4-385 

getting size of, (vol. 1) 4-184 
CheckMenultem function, (vol. 1) 1-56, 4-25, 4-311 
CheckRadioButton function, (vol. 1) 1-43, 4-26 
Child window 

clipping, (vol. 2) 8-16 

described, (vol. 1) 1-23 
ChildWindowFromPoint function, (vol. 1) 1-57, 2-20, 
4-26 
?CHKSTK, Cmacro, (vol. 2) 13-6 
Chord function, (vol. 1) 2-24 to 2-25, 4-27 
Class 

Application Global, (vol. 1) 1-9 

Application Local, (vol. 1) 1-9 


class background brush 
assigning, (vol. 1) 1-13 
setting, (vol. 1) 1-13 
class name 
assigning, (vol. 1) 1-11 
global uniqueness, (vol. 1) 1-11 
creating, (vol. 1) 1-8 
Cursor, (vol. 1) 1-12 
defining and registering, (vol. 1) 1-8 
determining ownership, (vol. 1) 1-9 
display contexts, (vol. 1) 1-18 
elements, (vol. 1) 1-10 
assigning, (vol. 1) 1-10 
class names, (vol. 1) 1-10 
instance handle, (vol. 1) 1-12 
functions 
default messages, (vol. 1) 1-20 
defining, (vol. 1) 1-18, 1-20 
examining, (vol. 1) 1-18, 1-20 
receiving, (vol. 1) 1-18, 1-20 
responding, (vol. 1) 1-18, 1-20 
icon, (vol. 1) 1-12 
menu, (vol. 1) 1-14 
messages 
declaring, (vol. 1) 1-20 
sending, (vol. 1) 1-20 
values, (vol. 1) 1-20 
predefined, (vol. 1) 1-10 
redrawing client area, (vol. 1) 1-17 
registering, (vol. 1) 1-9, 1-20 
shared, (vol. 1) 1-10 
styles 
child, (vol. 1) 1-23 
described, (vol. 1) 1-14 to 1-15 
overlapped, (vol. 1) 1-22 
owned, (vol. 1) 1-22 
pop-up, (vol. 1) 1-23 
System Global, (vol. 1) 1-8 
window, unregistering, (vol. 1) 4-452 
CLASS resource statement, (vol. 2) 8-19 
ClearCommBreak function, (vol. 1) 3-11, 4-28 
Client area 
child window, (vol. 1) 1-23 
painting, (vol. 2) 7-55 
redrawing, (vol. 1) 1-17 
update region, (vol. 1) 1-38 
CLIENTCREATESTRUCT data structure, (vol. 1) 1-25, 
5-19, (vol. 2) 7-16 
ClientToScreen function, (vol. 1) 2-20, 4-28 
CLIP_TO_PATH printer escape, (vol. 2) 12-6 
Clipboard 
file format, (vol. 2) 9-5 
formats, (vol. 1) 4-370 


functions, (vol. 1) 1-58 
getting prioritized format, (vol. 1) 4-197 
CLIPCAPS device capability, (vol. 1) 4-167 
ClipCursor function, (vol. 1) 1-62, 4-29 
Clipping, child window, (vol. 2) 8-16 
Clipping functions, (vol. 1) 2-22 to 2-23 
Clipping region, default, (vol. 1) 1-33 
CloseClipboard function, (vol. 1) 1-59, 4-29 
CloseComm function, (vol. 1) 3-11, 4-29 
CloseMetaFile function, (vol. 1) 2-41, 4-30 
CloseSound function, (vol. 1) 3-12, 4-30 
Close Window function, (vol. 1) 1-28, 4-30 
CLRDTR communication function code, (vol. 1) 4-128 
CLRRTS communication function code, (vol. 1) 4-128 
Cmacro 
Arg macro, arguments, position of, (vol. 2) 14-2 to 14-3 
assumes macro, (vol. 2) 14-2 
BITBLT sample function, (vol. 2) 13-9 
call macros, (vol. 2) 13-8 
calling convention, (vol. 2) 13-3 
calling cProc function, (vol. 2) 13-8 
calling high-level-language function, (vol. 2) 13-8 
cBegin macro, (vol. 2) 14-2 
cCall macro, (vol. 2) 13-8 
cEnd macro, (vol. 2) 14-3 
codeOFFSET macro, (vol. 2) 14-4 
cProc macro, (vol. 2) 13-8 
createSeg macro, (vol. 2) 14-6 
dataOFFSET macro, (vol. 2) 14-6 
defined, (vol. 2) 13-6, 14-1 
DefX macro, (vol. 2) 14-7 
erm$ macro, (vol. 2) 14-7 
ermz macro, (vol. 2) 14-8 
Error macros, (vol. 2) 13-9 
example, (vol. 2) 13-9, 13-10 
externX macro, (vol. 2) 14-9 
FarPtr macro, (vol. 2) 14-9 
function, (vol. 2) 13-8 
globalX macro, (vol. 2) 14-10 
INCLUDE directive, (vol. 2) 13-4 
labelX macro, (vol. 2) 14-11 
localX macro, (vol. 2) 13-9, 14-11 
memory-model options, (vol. 2) 13-2 
options, (vol. 2) 13-1 
overriding type, (vol. 2) 13-9 
parmX macro, (vol. 2) 13-9 to 13-10, 14-5 
?PLM option, (vol. 2) 13-4, 13-8 
Save macro, (vol. 2) 14-14 
sBegin macro, (vol. 2) 14-14 
segment macros 
CODE segment, (vol. 2) 14-6 
DATA segment, (vol. 2) 14-6 
described, (vol. 2) 13-6 
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segNameOFFSET macro, (vol. 2) 14-14 

sEnd macro, (vol. 2) 14-15 

special-definitions macros, (vol. 2) 13-8 

stack-checking option, (vol. 2) 13-6 

staticX macro, (vol. 2) 14-15 

storage-allocation macros, (vol. 2) 13-7 

symbol redefinition, (vol. 2) 13-10 

2WIN option, (vol. 2) 13-4 

Windows prolog/epilog, (vol. 2) 13-4 
CMACROS.INC file, (vol. 2) 13-4 
CODE module-definition statement, (vol. 2) 10-2 
Code segment attributes, defining, (vol. 2) 10-2, 10-8 
CODE segment, Cmacro, (vol. 2) 14-6 
CODE statement, (vol. 2) 10-1 
codeOFFSET macro, Cmacro, (vol. 2) 14-4 
Coding instruction sequences, (vol. 2) 13-9 
Color 

data types, (vol. 2) 7-17 

explicit RGB, (vol. 2) 7-17 

logical-palette index, (vol. 1) 4-327, (vol. 2) 7-17 

palette-relative RGB, (vol. 2) 7-17 

specifying, (vol. 2) 7-17 ‘ 

using color in logical palette, (vol. 1) 4-327 to 4-328 
COLOR_ACTIVEBORDER system color, (vol. 1) 4-401 
COLOR_ACTIVECAPTION system color, (vol. 1) 1-13, 
4-401 
COLOR_APPWORKSPACE system color, (vol. 1) 1-13, 
4-401 
COLOR_BACKGROUND system color, (vol. 1) 1-13, 
4-401 
COLOR_BTNFACE system color, (vol. 1) 1-13, 4-401 
COLOR_BTNSHADOW system color, (vol. 1) 1-13, 
4-401 
COLOR_BTNTEXT system color, (vol. 1) 4-401 
COLOR_CAPTIONTEXT system color, (vol. 1) 1-13, 
4-401 
COLOR_GRAYTEXT system color, (vol. 1) 1-13, 
4-250, 4-401 
COLOR_HIGHLIGHT system color, (vol. 1) 1-13, 4-401 
COLOR_HIGHLIGHTTEXT system color, (vol. 1) 1-13, 
4-401 
COLOR_INACTIVEBORDER system color, (vol. 1) 
4-401 
COLOR_INACTIVECAPTION system color, (vol. 1) 
1-13, 4-401 
COLOR_MENU system color, (vol. 1) 1-13, 4-401 
COLOR_MENUTEXT system color, (vol. 1) 1-13, 4-401 
Color palette 

See also Logical palette 

default, (vol. 1) 1-33 

updating client area, (vol. 1) 4-452 
COLOR_SCROLLBAR system color, (vol. 1) 1-13, 
4-401 
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COLOR_WINDOW system color, (vol. 1) 1-13, 4-401 
COLOR_WINDOWFRAME system color, (vol. 1) 1-13, 
4-401 

COLOR_WINDOWTEXT system color, (vol. 1) 1-13, 
4-401 

COLORONCOLAOR stretching mode, (vol. 1) 4-399 


COLORREF data type, (vol. 1) 2-9, 3-13, (vol. 2) 7-17 to 


7-18 
Combine type, segments, (vol. 2) 14-6 
CombineR gn function, (vol. 1) 2-21, 4-31 
Combo box 
deleted item, (vol. 2) 7-26 
described, (vol. 1) 1-50 
owner-draw 
described, (vol. 1) 1-50 to 1-51 
new item position, (vol. 1) 6-53 
sorting, (vol. 2) 7-19 
COMBOBOxX control class 
control styles, (vol. 1) 4-69, (vol. 2) 8-32, 8-38 
described, (vol. 1) 4-64, (vol. 2) 8-32, 8-35 
COMBOBOx resource statement 
described, (vol. 2) 8-31 to 8-32 
DIALOG resource statement, (vol. 2) 8-20 
Command, Cmacro 
EQU, (vol. 2) 13-3 
INCLUDE, (vol. 2) 13-4 
COMMON combine type, Cmacro, (vol. 2) 14-6 
Communication devices, (vol. 2) 7-20, 7-22 
COMPAREITEMSTRUCT data structure, (vol. 1) 6-53, 
(vol. 2) 7-19 
COMPLEXREGION region type, (vol. 1) 4-32, 4-129, 
4-158, 4-224, 4-260, 4-318 to 4-319, 4-359 
COMSTAT data structure, (vol. 2) 7-20 
Contexts 
class and private, (vol. 1) 1-18 
classes, displaying, (vol. 1) 1-34 
displaying, (vol. 1) 1-32 
displaying cache, (vol. 1) 1-36 
displaying common defaults, (vol. 1) 1-33 
painting changes, (vol. 1) 1-36 
private display, (vol. 1) 1-35 
window display, (vol. 1) 1-35 
WM_PAINT message, (vol. 1) 1-36 
Control 
current font, (vol. 1) 6-62 
owner-draw See Control, owner-draw 
setting current font, (vol. 1) 6-99 
size-box, (vol. 2) 8-36 
Control class 
BUTTON 
control styles, (vol. 2) 8-37 
described, (vol. 2) 8-35 
* COMBOBOX 


control styles, (vol. 1) 4-69 
described, (vol. 1) 4-64, (vol. 2) 8-35 

control styles, described, (vol. 2) 8-37 

described, (vol. 2) 8-35 

EDIT, (vol. 2) 8-36 

EDIT, control styles, (vol. 2) 8-39 

LISTBOX, (vol. 2) 8-36 

LISTBOX control styles, (vol. 2) 8-41 

SCROLLBAR, (vol. 2) 8-36. 

SCROLLBAR control styles, (vol. 2) 8-43 

STATIC, (vol. 2) 8-36 
Control, edit See Edit control 
CONTROL option, ACCELERATORS resource 
statement, (vol. 2) 8-8 
Control, owner-draw 

described, (vol. 1) 1-50 

drawing, (vol. 1) 6-58, 6-79, (vol. 2) 7-36 

item deleted from, (vol. 2) 7-27 

measuring, (vol. 1) 6-79 
CONTROL resource statement 

described, (vol. 2) 8-34 to 8-35 

DIALOG resource statement, (vol. 2) 8-20 
Control styles 

BUTTON class, (vol. 2) 8-37. 

COMBOBOxX class, (vol. 1) 4-69, (vol. 2) 8-38 

- described, (vol. 2) 8-37 

EDIT class, (vol. 2) 8-39 

LISTBOX< class, (vol. 2) 8-41 

SCROLLBAR class, (vol. 2) 8-43 
Control text 

centered, (vol. 2) 8-22 

left-justified, (vol. 2) 8-20 

right-justified, (vol. 2) 8-21 
Control window, user-defined, (vol. 2) 8-34 
Coordinate functions, (vol. 1) 2-20 
CopyMetaFile function, (vol. 1) 2-41, 4-32 
CopyRect function, (vol. 1) 1-67, 4-32 
CountClipboardFormats function, (vol. 1) 4-33 
CountVoiceNotes function, (vol. 1) 3-12, 4-33 
cProc macro, Cmacro, (vol. 2) 13-8 
CreateBitmap function, (vol. 1) 2-25, 4-33 
CreateBitmapIndirect function, (vol. 1) 2-25, 4-34 
CreateBrushIndirect function, (vol. 1) 2-5, 4-35 
CreateCaret function, (vol. 1) 1-60, 4-35 
CreateCompatibleBitmap function, (vol. 1) 2-25, 4-36 
CreateCompatibleDC function, (vol. 1) 2-2, 4-37 
CreateCursor function, (vol. 1) 1-62, 4-38 
CreateDC function, (vol. 1) 2-2, 4-38 
CreateDialog function, (vol. 1) 1-43, 1-46, 4-39 to 4-40, 
4-44, 4-78 
CreateDialogIndirect function, (vol. 1) 1-43, 4-41 to 
4-42, 4-78, 6-100 
CreateDialogIndirectParam function, (vol. 1) 1-43, 4-43, 
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4-79, 6-100 
CreateDialogParam function, (vol. 1) 1-43, 4-44, 4-79 
CreateDIBitmap function, (vol. 1) 2-26, 4-44 to 4-45 
CreateDIBPatternBrush function, (vol. 1) 2-5, 4-46 
CreateDiscardableBitmap function, (vol. 1) 2-25, 4-46 
CreateEllipticRgn function, (vol. 1) 2-21, 4-47 
CreateEllipticRgnIndirect function, (vol. 1) 2-21, 4-48 
CreateFont function, (vol. 1) 2-28, 4-48 to 4-50 
CreateFontIndirect function, (vol. 1) 2-28, 4-51 
CreateHatchBrush function, (vol. 1) 2-5, 4-51 
CreateIC function, (vol. 1) 2-2, 4-52 
CreateIcon function, (vol. 1) 1-39, 4-53 
CreateMenu function, (vol. 1) 1-56, 4-54 
CreateMetaFile function, (vol. 1) 2-41, 4-54 
CreatePalette function, (vol. 1) 2-10, 4-7, 4-55, 4-361 
CreatePatternBrush function, (vol. 1) 2-6, 4-55 
CreatePen function, (vol. 1) 2-6, 4-56 
CreatePenIndirect function, (vol. 1) 2-6, 4-57 
CreatePolygonRgn function, (vol. 1) 2-21, 4-57 
CreatePolyPolygonRgn function, (vol. 1) 2-21, 4-58 
CreatePopupMenu function, (vol. 1) 1-26, 1-56, 4-59 
CreateRectRgn function, (vol. 1) 2-21, 4-59 
CreateRectRgnIndirect function, (vol. 1) 2-21, 4-60 
CreateRoundRectRgn function, (vol. 1) 2-21, 4-60 
createSeg macro, Cmacro, (vol. 2) 14-6 
CreateSolidBrush function, (vol. 1) 2-6, 4-61 
CREATESTRUCT data structure, (vol. 2) 7-21 
CreateWindow function, (vol. 1) 1-3 

creating a child window, (vol. 1) 1-23 

creating a window with dialog-box attributes, (vol. 2) 
8-15 

creating an overlapped window, (vol. 1) 1-22 

described, (vol. 1) 1-7, 4-61 to 4-75 
CreateWindowEx function, (vol. 1) 1-7, 4-4, 4-76 to 4-77 
Creating windows, (vol. 2) 8-15 
CS_BYTEALIGNCLIENT window class style, (vol. 1) 
1-14, (vol. 2) 7-62 
CS_BYTEALIGNWINDOW window class style, (vol. 1) 
1-14, (vol. 2) 7-62 
CS_CLASSDC window class style, (vol. 1) 1-14, 1-34, 
(vol. 2) 7-62 
CS_DBLCLKS window class style, (vol. 1) 1-14, (vol. 2) 
7-62 
CS_GLOBALCLASS window class style, (vol. 1) 1-15 
CS_HREDRAW window class style, (vol. 1) 1-15, (vol. 
2) 7-63 


CS_NOCLOSE window class style, (vol. 1) 1-15, (vol. 2) © 


7-63 

CS_OWNDC window class style, (vol. 1) 1-15, 1-17, 
1-35, (vol. 2) 7-63 

CS_PARENTDC window class style, (vol. 1) 1-15, (vol. 
2) 7-63 

CS_SAVEBITS window class style, (vol. 1) 1-15, (vol. 


2) 7-64 
CS_VREDRAW window class style, (vol. 1) 1-15, (vol. 
2) 7-64 
CTEXT resource statement, (vol. 2) 8-22 to 8-23 
CTLCOLOR_BTN control type for setting color, (vol. 1) 
6-54 
CTLCOLOR_DLG control type for setting color, (vol. 1) 
6-54 
CTLCOLOR_EDIT control type for setting color, (vol. 1) 
6-55 
CTLCOLOR_LISTBOX control type for setting color, 
(vol. 1) 6-55 
CTLCOLOR_MSGBOxX control type for setting color, 
(vol. 1) 6-55 
CTLCOLOR_SCROLLBAR control type for setting 
color, (vol. 1) 6-55 
CTLCOLOR_STATIC control type for setting color, 
(vol. 1) 6-55 
Curly braces ({ }), as document convention, (vol. 1) xxv, 
(vol. 2) x 
Cursor 

class, (vol. 1) 1-12 

confining, (vol. 1) 1-63 

creating custom, (vol. 1) 1-63 

displaying and hiding, (vol. 1) 1-62 

file format, (vol. 2) 9-3 

functions, (vol. 1) 1-61 

positioning, (vol. 1) 1-63 

resource, (vol. 2) 8-2 

with pointing devices, (vol. 1) 1-62 
CURSOR resource-compiler key word, (vol. 2) 8-2 
CURVECAPS device capability, (vol. 1) 4-168 
CW_USEDEFAULT default window width, (vol. 2) 7-47 


D 


DATA module-definition statement, (vol. 2) 10-2 
Data object, 32-bit, (vol. 2) E-7 

Data segment attributes, defining, (vol. 2) 10-2, 10-8 
DATA segment, Cmacro, (vol. 2) 14-6 

DATA statement, (vol. 2) 10-1 

Data types, naming conventions, (vol. 2) 7-1, 7-5 
dataOFFSET macro, Cmacro, (vol. 2) 14-6 
DC_BINS device capability, (vol. 1) 4-91 
DC_DRIVER device capability, (vol. 1) 4-92 
DC_DUPLEX device capability, (vol. 1) 4-92 
DC_EXTRA device capability, (vol. 1) 4-92 
DC_FIELDS device capability, (vol. 1) 4-92 
DC_MAXEXTENT device capability, (vol. 1) 4-92 
DC_MINEXTENT device capability, (vol. 1) 4-92 
DC_PAPERS device capability, (vol. 1) 4-93 
DC_PAPERSIZE device capability, (vol. 1) 4-93 
DC_SIZE device capability, (vol. 1) 4-93 
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DC_VERSION device capability, (vol. 1) 4-93 
DCB data structure, (vol. 2) 7-22 to 7-25 
DDE 

messages, (vol. 2) 15-1 

protocol, (vol. 2) 15-1 
DebugBreak function, (vol. 1) 3-14, 4-78 
.DEF file. See Module-definition file 
DEFAULT_PALETTE stock object, (vol. 1) 4-208 
Default pushbutton control, (vol. 2) 8-28 
DefDlgProc function, (vol. 1) 1-7, 1-43, 4-78, (vol. 2) 
8-19 
DeferWindowPos function, (vol. 1) 1-28, 4-79 to 4-80 
DefFrameProc function, (vol. 1) 1-7, 4-81 
DefHookProc function, (vol. 1) 1-63, 4-82 
#define directive, resource compiler, (vol. 2) 8-48 
DefineHandleTable function, (vol. 1) 3-3, 3-5, 4-83 
DefMDIChildProc function, (vol. 1) 1-7, 4-84 
DEFPUSHBUTTON resource statement 

described, (vol. 2) 8-28 to 8-29 

DIALOG resource statement, (vol. 2) 8-20 
DefWindowProc function, (vol. 1) 1-7, 4-85 
DefX macro, Cmacro, (vol. 2) 14-7 
DeleteAtom function, (vol. 1) 3-9, 4-86 
DeleteDC function, (vol. 1) 2-2, 4-37, 4-86 
DELETEITEMSTRUCT data structure 

as parameter of WM_DELETEITEM message, (vol. 1) 
6-57 

described, (vol. 2) 7-26 
DeleteMenu function, (vol. 1) 1-56, 4-87 
DeleteMetaFile function, (vol. 1) 2-41, 4-87 
DeleteObject function, (vol. 1) 2-6, 4-88, 6-99 
DESCRIPTION module-definition statement, (vol. 2) 
10-3 
DESCRIPTION statement, (vol. 2) 10-1 
DestroyCaret function, (vol. 1) 1-60, 4-88 
DestroyCursor function, (vol. 1) 1-62, 4-89 
DestroyMenu function, (vol. 1) 1-56, 4-90 
Destroy Window function 

described, (vol. 1) 1-7, 4-90 

destroying modeless dialog boxes, (vol. 1) 1-45 

effect, (vol. 1) 1-28 
Device context 

attributes and functions, (vol. 1) 2-3 

creating, saving and deleting, (vol. 1) 2-4 

functions, described, (vol. 1) 2-2 
DEVICE_DEFAULT_FONT stock object, (vol. 1) 4-207 
Device driver, device capabilities, (vol. 1) 4-91 
Device-independent bitmap. See Bitmap, 
device-independent 
DeviceCapabilities function, (vol. 1) 2-44, 4-91 to 4-93 
DEVICEDATA printer escape, (vol. 2) 12-7. See 
PASSTHROUGH printer escape 
DeviceMode function, (vol. 1) 2-44, 4-94 


Devices, communication, (vol. 2) 7-20, 7-22 
DEVMODE data structure, (vol. 1) 4-92 to 4-93, 4-131, 
(vol. 2) 7-27 to 7-30 
Dialog box 
accelerators, (vol. 1) 1-52 
buttons, (vol. 1) 1-49 
control identifiers, (vol. 1) 1-48 
control styles, (vol. 1) 1-48 
controls 
control messages, (vol. 1) 1-51 
described, (vol. 1) 1-47, 1-51 
creating, (vol. 1) 1-45 to 1-46, (vol. 2) 7-31, 8-13 
described, (vol. 1) 1-43 _. 
dimensions, (vol. 1) 1-51 
edit controls, (vol. 1) 1-49 
input function, (vol. 1) 1-46 
items, (vol. 2) 7-34 
keyboard input, (vol. 1) 1-52 
keyboard interface 
actions, (vol. 1) 1-51 
filtering, measurements, (vol. 1) 1-52 
scrolling, (vol. 1) 1-52 
modal 
creating, (vol. 1) 1-46, 4-98 to 4-99 
moveable, (vol. 1) 1-45 
modeless 
creating, (vol. 1) 4-43 to 4-44 
deleting, (vol. 1) 1-45 
using, (vol. 1) 1-45 
owner draw, (vol. 1) 1-51 
private window class default function, (vol. 1) 4-78 
redrawing, (vol. 1) 1-51 
return values, (vol. 1) 1-47 
scrolling, (vol. 1) 1-52 
template, (vol. 1) 1-46, (vol. 2) 8-13 
text font, (vol. 2) 7-34 
using, (vol. 1) 1-45 
window style, (vol. 2) 8-15 
Dialog box units, (vol. 2) 8-21 to 8-30, 8-32 
Dialog functions, (vol. 1) 1-43 
Dialog option statements, (vol. 2) 8-15 
DIALOG resource statement 
control class, control styles, (vol. 2) 8-37 
described, (vol. 2) 8-13 
dialog control statements _ 
CHECKBOX, (vol. 2) 8-20, 8-23 
COMBOBOXx, (vol. 2) 8-20, 8-31 
CONTROL, (vol. 2) 8-20, 8-34 
control classes, (vol. 2) 8-35 
CTEXT, (vol. 2) 8-20, 8-22 
DEFPUSHBUTTON, (vol. 2) 8-20, 8-28 
EDITTEXT, (vol. 2) 8-20, 8-30 
GROUPBOX, (vol. 2) 8-20, 8-27 


ICON, (vol. 2) 8-20, 8-33 

LISTBOX, (vol. 2) 8-20, 8-26 

LTEXT, (vol. 2) 8-20 

PUSHBUTTON, (vol. 2) 8-20, 8-25 

RADIOBUTTON, (vol. 2) 8-20, 8-29 

RTEXT, (vol. 2) 8-20 to 8-21 

SCROLLBAR, (vol. 2) 8-33 

dialog option statement 

CAPTION, (vol. 2) 8-15, 8-18 

CLASS, (vol. 2) 8-15, 8-19 

FONT, (vol. 2) 8-15, 8-19 

MENU, (vol. 2) 8-15, 8-18 

STYLE, (vol. 2) 8-14 to 8-15 
DIALOG template, (vol. 2) 8-13 


DialogBox function, (vol. 1) 1-43, 1-46, 4-79, 4-95, (vol. 


2) 8-14 
DialogBoxIndirect function, (vol. 1) 1-43, 4-79, 4-96 to 
4-97, 6-100 
DialogBoxIndirectParam function, (vol. 1) 1-43, 4-79, 
4-98, 6-100 
DialogBoxParam function, (vol. 1) 1-43, 4-79, 4-99 
DIB. See Bitmap, device-independent 
DIB_PAL_COLORS, device-independent bitmap color 
table option, (vol. 1) 4-45 to 4-46, 4-172, 4-376, 4-378, 
4-436, (vol. 2) 7-9, 7-12, 7-39, 9-15 
DIB_RGB_COLORS, device-independent bitmap color 
table option, (vol. 1) 4-45 to 4-46, 4-172, 4-376, 4-378, 
4-436, (vol. 2) 7-39, 9-15 
Digitized aspect, fonts, (vol. 1) 2-36 
Directive, resource compiler 

#define, (vol. 2) 8-48 

described, (vol. 2) 8-47 

#elif, (vol. 2) 8-50 

#else, (vol. 2) 8-50 - 

#endif, (vol. 2) 8-51 ' 

#if, (vol. 2) 8-49 

#ifdef, (vol. 2) 8-48 

#ifndef, (vol. 2) 8-49 

#include, (vol. 2) 8-47 

#undef, (vol. 2) 8-48 
Disabled window, (vol. 2) 8-14 
DISCARDABLE resource-compiler key word, (vol. 2) 
8-2, 8-4 to 8-6, 8-9, 8-14 
DispatchMessage function, (vol. 1) 1-2, 4-99 
Display context default characteristics, (vol. 1) 1-33 
Display, updating, (vol. 1) 1-37 
DKGRAY_BRUSH stock object, (vol. 1) 4-207 
DLGC_DEFPUSHBUTTON input type, (vol. 1) 6-62 
DLGC_HASSETSEL input type, (vol. 1) 6-62 
DLGC_PUSHBUTTON input type, (vol. 1) 6-62 
DLGC_RADIOBUTTON input type, (vol. 1) 6-62 
DLGC_WANTALLKEYS input type, (vol. 1) 6-62 
DLGC_WANTARROWS input type, (vol. 1) 6-62 
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DLGC_WANTCHARS input type, (vol. 1) 6-62 
DLGC_WANTMESSAGE input type, (vol. 1) 6-62 
DLGC_WANTTAB input type, (vol. 1) 6-62 
DlgDirList function, (vol. 1) 1-43, 4-100 to 4-101 
DlgDirListComboBox function, (vol. 1) 1-43, 4-102 
DlgDirSelect function, (vol. 1) 1-44, 4-103 
DlgDirSelectComboBox function, (vol. 1) 1-44, 4-104 
DLGITEMTEMPLATE data structure, (vol. 2) 7-34 
DLGTEMPLATE 

data structure, (vol. 1) 6-100, (vol. 2) 7-31 to 7-35 

DLGITEMTEMPLATE data structure, (vol. 2) 7-34 

FONTINFO data structure, (vol. 2) 7-34 
DM_COPY option, (vol. 1) 4-131 
DM_GETDEFID message, (vol. 1) 5-9, 6-19 
DM_MODIFY option, (vol. i) 4-132 
DM_PROMPT option, (vol. 1) 4-132 
DM_SETDEFID message, (vol. 1) 5-9, 6-19 
DM_UPDATE option, (vol. 1) 4-132 
Document conventions 

bold text, (vol. 1) xxiv 

curly braces ({ }), (vol. 1) xxv 

double brackets ([[]), (vol. 1) xxv 

horizontal ellipses (. . .), (vol. 1) xxiv 

monospaced type, (vol.-1) xxiv 

italic text, (vol. 1) xxiv 

parentheses ( ), (vol. 1) xxiv 

quotation marks (“”’), (vol. 1) xxv 

small capital letters, (vol. 1) xxv 

vertical bar (I), (vol. 1) xxv 

vertical ellipses, (vol. 1) xxiv 
DOS interrupt function request (21H), (vol. 1) 4-104 
DOS3Call function, (vol. 1) 3-6, 4-104 
Double brackets ({[]]), as document convention, (vol. 1) 
XXV 
Double quotation marks (“”’), (vol. 2) 8-6 to 8-7, 8-10, 
8-19 
DPtoLP function, (vol. 1) 2-20, 4-105 
DRAFT_QUALITY font quality, (vol. 2) 7-43 
DRAFTMODE printer escape, (vol. 2) 12-7 
DrawFocusRect function, (vol. 1) 1-31, 2-24, 4-106 
Drawlcon function, (vol. 1) 1-31, 4-106 
Drawing 

formatted text, (vol. 1) 1-40 

gray text, (vol. 1) 1-42 

icons, (vol. 1) 1-39 : 

mode, default, (vol. 1) 1-33 
DRAWITEMSTRUCT 

as parameter of WM_DRAWITEM message, (vol. 1) 
6-59 

data structure, described, (vol. 2) 7-36 to 7-37 
DrawMenuBar function, (vol. 1) 1-56, 4-12, 4-87, 4-107, 
4-257, 4-311, 4-350 
DRAWPATTERNRECT printer escape, (vol. 2) 12-8 
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DrawText function, (vol. 1) 1-31, 4-107 to 4-109 
Driver, printer initialization, (vol. 2) 7-27 
DRIVERVERSION device capability, (vol. 1) 4-167 
Drop-down menu. See Pop-up menu 

DS_ABSALIGN dialog-box style, (vol. 2) 7-32, 8-14 to 
8-15 

DS_LOCALEDIT dialog-box style, (vol. 1) 4-66, (vol. 2) 
7-32, 8-16 

DS_MODALFRAME dialog-box style, (vol. 1) 4-66, 
(vol. 2) 7-32, 8-16 

DS_NOIDLEMSG dialog-box style, (vol. 1) 4-66, (vol. 
2) 7-33, 8-16 

DS_SETFONT dialog-box style, (vol. 1) 6-100, (vol. 2) 
7-32 

DS_SYSMODAL dialog-box style, (vol. 1) 4-66, (vol. 2) 
7-32, 8-16 

DSTINVERT raster operation, (vol. 1) 4-19 
DT_BOTTOM format for DrawText function, (vol. 1) 
4-108 

DT_CALCRECT format for DrawText function, (vol. 1) 
4-108 

DT_EXPANDTABS format for DrawText function, (vol. 
1) 4-108 

DT_EXTERNALLEADING format for DrawText 
function, (vol. 1) 4-108 

DT_NOCLIP format for DrawText function, (vol. 1) 
4-108 

DT_NOPREFIX format for DrawText function, (vol. 1) 
4-109 

DT_SINGLELINE format for DrawText function, (vol. 
1) 4-109 

DT_TABSTOP format for DrawText function, (vol. 1) 
4-109 

DT_TOP format for DrawText function, (vol. 1) 4-109 
DT_VCENTER format for DrawText function, (vol. 1) 
4-109 

DT_WORDBREAK format for DrawText function, (vol. 
1) 4-109 

DUP assembler operator, (vol. 2) 14-15 

DWORD data type, (vol. 2) 7-1. 

Dynamic Data Exchange. See DDE 


E 


Edit control 
described, (vol. 2) 8-30 to 8-31, 8-40 
tab stops in, (vol. 1) 6-28 
EDIT control class 
control styles, (vol. 2) 8-31, 8-39 
described, (vol. 1) 4-64, (vol. 2) 8-36 
Edit-control notification codes, (vol. 1) 5-16 
Editing keys, (vol. 2) 8-30 
EDITTEXT resource statement 


described, (vol. 2) 8-30 to 8-31 

style option, (vol. 2) 8-30 
EDITTEXT statement, DIALOG resource statement, 
(vol. 2) 8-20 
#elif directive, resource compiler, (vol. 2) 8-50 
Ellipse function, (vol. 1) 2-24 to 2-25, 4-110 
Ellipses 

horizontal, as document convention, (vol. 1) xxiv 

vertical, as document convention, (vol. 1) xxiv 
#else directive, resource compiler, (vol. 2) 8-50 
EM_CANUNDO message, (vol. 1) 5-10, 6-20 
EM_EMPTYUNDOBUFFER message, (vol. 1) 5-10, 
6-20 
EM_FMTLINES message, (vol. 1) 5-10, 6-20 
EM_GETHANDLE message, (vol. 1) 5-10, 6-21 
EM_GETLINE message, (vol. 1) 5-10, 6-21 
EM_GETLINECOUNT message, (vol. 1) 5-10, 6-22 
EM_GETMODIFY message, (vol. 1) 5-10, 6-22 
EM_GETRECT message, (vol. 1) 5-10, 6-22 
EM_GETSEL message, (vol. 1) 5-10, 6-23 
EM_LIMITTEXT message, (vol. 1) 5-10, 6-23 
EM_LINEFROMCHAR message, (vol. 1) 5-10, 6-23 
EM_LINEINDEX message, (vol. 1) 5-10, 6-24 
EM_LINELENGTH message, (vol. 1) 5-10, 6-24 
EM_LINESCROLL message, (vol. 1) 5-10, 6-25 
EM_REPLACESEL message, (vol. 1) 5-11, 6-25 
EM_SETHANDLE message, (vol. 1) 5-11, 6-26 
EM_SETMODIFY message, (vol. 1) 5-11, 6-26 
EM_SETPASSWORDCHAR message, (vol. 1) 4-71, 
5-11, 6-26, (vol. 2) 8-40 
EM_SETRECT message, (vol. 1) 5-11, 6-27 
EM_SETRECTNP message, (vol. 1) 5-11, 6-27 - 
EM_SETSEL message, (vol. 1) 5-11, 6-28 
EM_SETTABSTOPS message, (vol. 1) 5-11, 6-28 
EM_SETWORDBREAK message, (vol. 1) 5-11, 6-29 
EM_UNDO message, (vol. 1) 5-11, 6-30 
EmptyClipboard function, (vol. 1) 1-59, 4-110 
EMS memory, determining available, (vol. 1) 4-177 
EN_CHANGE message, (vol. 1) 5-16, 6-30 
EN_ERRSPACE message, (vol. 1) 5-16, 6-30 
EN_HSCROLL message, (vol. 1) 5-16, 6-31 
EN_KILLFOCUS message, (vol. 1) 5-16, 6-31 
EN_MAXTEXT message, (vol. 1) 5-16, 6-31 
EN_SETFOCUS message, (vol. 1) 5-16, 6-32 
EN_UPDATE message, (vol. 1) 5-16, 6-32 
EN_VSCROLL message, (vol. 1) 5-16, 6-33 
ENABLEDUPLEX printer escape, (vol. 2) 12-9 
EnableHardwarelInput function, (vol. 1) 1-30, 4-111 
EnableMenultem function, (vol. 1) 1-56, 4-111, 4-311 
ENABLEPAIRKERNING printer escape, (vol. 2) 12-10 
ENABLERELATIVEWIDTHS printer escape, (vol. 2) 
12-11 
EnableWindow function, (vol. 1) 1-29, 4-112 
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END_PATH printer escape, (vol. 2) 12-12 to 12-14 
EndDeferWindowPos function, (vol. 1) 1-28, 4-113 
EndDialog function, (vol. 1) 1-44, 4-99, 4-113 
ENDDOC printer escape, (vol. 2) 12-12 
#endif directive, resource compiler, (vol. 2) 8-51 
EndPaint function, (vol. 1) 1-31, 4-114 
Entry point 

creating, (vol. 2) 13-5 

function, (vol. 2) 14-2 
EnumChildWindows function, (vol. 1) 1-57, 4-115 
EnumClipboardFormats function, (vol. 1) 1-59, 4-116 
EnumFonts function, (vol. 1) 2-28, 4-117 
EnumMetaFile function, (vol. 1) 2-41, 4-118 to 4-119 
EnumObjects function, (vol. 1) 2-6, 4-120 
ENUMPAPERBINS printer escape, (vol. 1) 4-91, (vol. 2) 
12-15 
ENUMPAPERMETRICS printer escape, (vol. 2) 12-16 
EnumProps function, (vol. 1) 1-65, 4-121 to 4-122 
EnumTask Windows function, (vol. 1) 1-57, 4-123 to 
4-124 
EnumWindows function, (vol. 1) 1-57, 4-125 
Epilog, Windows, (vol. 2) 13-4 
EPSPRINTING printer escape, (vol. 2) 12-16 
EQU directive, Cmacro, (vol. 2) 13-3 
EqualRect function, (vol. 1) 1-67, 4-126 
EqualRgn function, (vol. 1) 2-21, 4-126 
ermn$ macro, Cmacro, (vol. 2) 14-7 
ermz macro, Cmacro, (vol. 2) 14-8 
Error macros, Cmacro, (vol. 2) 13-9 
ERROR region type, (vol. 1) 4-32, 4-129, 4-158, 4-224, 
4-260, 4-318 to 4-319, 4-359 . 
ES_AUTOHSCROLL control style, (vol. 1) 4-70, (vol. 
2) 8-41 
ES_AUTOVSCROLL control style, (vol. 1) 4-70, (vol. 
2) 8-40 to 8-41 
ES_CENTER control style, (vol. 1) 4-70, (vol. 2) 8-39 
ES_LEFT control style, (vol. 1) 4-70, (vol. 2) 8-39 
ES_LOWERCASE control style, (vol. 1) 4-70, (vol. 2) 
8-39 
ES_MULTILINE control style, (vol. 1) 4-70, (vol. 2) 8-40 
ES_NOHIDESEL control style, (vol. 1) 4-71, (vol. 2) 
8-41 
ES_OEMCONVERT control style, (vol. 1) 4-71, (vol. 2) 
8-41 
ES_PASSWORD control style, (vol. 1) 4-71, (vol. 2) 8-40 
ES_RIGHT control style, (vol. 1) 4-71, (vol. 2) 8-39 
ES_UPPERCASE control style, (vol. 1) 4-71, (vol. 2) 
8-40 
Escape character 

\a, (vol. 2) 8-10 

\t, (vol. 2) 8-10 
Escape function, (vol. 1) 4-126 
EscapeCommFunction function, (vol. 1) 3-11, 4-127 


Escapes, printer, (vol. 2) 12-1 

EV_BREAK event-mask value, (vol. 1) 4-373 
EV_CTS event-mask value, (vol. 1) 4-373 

EV_DSR event-mask value, (vol. 1) 4-373 

EV_ERR event-mask value, (vol. 1) 4-373 

EV_PERR event-mask value, (vol. 1) 4-373 
EV_RING event-mask value, (vol. 1) 4-373 
EV_RLSD event-mask value, (vol. 1) 4-373 
EV_RXCHAR event-mask value, (vol. 1) 4-373 
EV_RXFLAG event-mask value, (vol. 1) 4-373 
EV_TXEMPTY event-mask value, (vol. 1) 4-373 
EVENPARITY parity type, (vol. 2) 7-23 
ExcludeClipRect function, (vol. 1) 2-22, 4-128 
ExcludeUpdateRgn function, (vol. 1) 1-31, 4-129 
EXETYPE module-definition statement, (vol. 2) 10-4 
Exit point, function, (vol. 2) 14-3 

ExitWindows function, (vol. 1) 3-6, 4-130 

Exporting function, (vol. 2) 10-7 

EXPORTS module-definition statement, (vol. 2) 10-4 
EXPORTS statement, (vol. 2) 10-1 
EXT_DEVICE_CAPS printer escape, (vol. 2) 12-17 to 
12-18 

ExtDeviceMode function, (vol. 1) 2-44, 4-130 to 4-132 
Extents, viewport and window default, (vol. 1) 1-33 
externX macro, Cmacro, (vol. 2) 14-9 

ExtFloodFill function, (vol. 1) 2-25, 4-133 
ExtTextOut function, (vol. 1) 2-27, 4-134 to 4-135 
EXTTEXTOUT printer escape, (vol. 2) 12-19 to 12-20 


F 


FAR data type, (vol. 2) 7-1 
FAR function type, Cmacro, (vol. 2) 13-10 
FARPROC data type, (vol. 2) 7-1 
FarPtr 
cCall, use with, (vol. 2) 14-9 
macro, Cmacro, (vol. 2) 14-9 
FatalAppExit function, (vol. 1) 3-14, 4-136 
FatalExit function, (vol. 1) 3-14, 4-136 
FF_DECORATIVE font family, (vol. 2) 7-44 
FF_DONTCARE font family, (vol. 2) 7-44 
FF_MODERN font family, (vol. 2) 7-44 
FF_ROMAN font family, (vol. 2) 7-44 
FF_SCRIPT font family, (vol. 2) 7-44 
FF_SWISS font family, (vol. 2) 7-44 
File 
bitmap, device-independent, format, (vol. 2) 9-1 
clipboard format, (vol. 2) 9-5 
closing, (vol. 1) 4-271 
CMACROS.INCG, (vol. 2) 13-4 
creating, (vol. 1) 4-271 
cursor format, (vol. 2) 9-3 
help, displaying, (vol. 1) 4-460 
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icon format, (vol. 2) 9-2 
initialization 
application-specific, (vol. 1) 4-199, 4-463 
WINDOWS.H, (vol. 2) 8-15 
metafile format, (vol. 2) 9-6 
module-definition file format, (vol. 2) 10-1 
opening, (vol. 1) 4-294 
positioning the pointer, (vol. 1) 4-274 
reading, (vol. 1) 4-297 
writing, (vol. 1) 4-300 
Filling mode 
ALTERNATE, (vol. 1) 4-58, 4-389 
WINDING, (vol. 1) 4-58, 4-389 
FillRect function, (vol. 1) 1-31, 4-137 
FillRgn function, (vol. 1) 2-21, 4-138 
Filters, installing, (vol. 1) 1-65 
FindAtom function, (vol. 1) 3-9, 4-138 
FindResource function, (vol. 1) 3-7, 4-139 
FindWindow function, (vol. 1) 1-57, 4-140 
Fixed-pitch font attribute, (vol. 1) 2-35 
FIXED resource-compiler key word, (vol. 2) 8-2 to 8-3, 
8-5 to 8-6, 8-9, 8-13. 
FlashWindow function, (vol. 1) 1-59, 4-141 
Flat memory model, (vol. 2) E-2, E-5 
FloodFill function, (vol. 1) 2-25, 4-141 
FlushComm function, (vol. 1) 3-11, 4-142 
FLUSHOUTPUT printer escape, (vol. 2) 12-21 
Font functions, (vol. 1) 2-28 to 2-29 
Font mapping characteristics, (vol. 1) 2-38 to 2-39 
FONT resource-compiler key word, (vol. 2) 8-2 
FONT resource statement, (vol. 2) 8-19 
Font Selection, (vol. 1) 2-40 
FONTINFO data structure, (vol. 1) 6-100, (vol. 2) 7-34 
Fonts 
average character width, (vol. 1) 2-35 
character sets 
ANSI, (vol. 1) 2-35 
described, (vol. 1) 2-34 
OEM, (vol. 1) 2-35 
printer, (vol. 1) 2-35 
vendor specific, (vol. 1) 2-35 
control, current, (vol. 1) 6-62 
default, (vol. 1) 1-33 
digitized aspect, (vol. 1) 2-36 
family 
described, (vol. 1) 2-29 
italic, bold, and underline, (vol. 1) 2-32 
leading, (vol. 1) 2-33 to 2-34 
logical, creating, (vol. 1) 4-48, 4-51, (vol. 2) 7-40 
maximum character width, (vol. 1) 2-36 
overhang, (vol. 1) 2-36 
pitch, (vol. 1) 2-35 
resource, (vol. 2) 8-2 


setting in control, (vol. 1) 6-99 
Formats, clipboard, (vol. 1) 4-370 
Formatted text, styles, (vol. 1) 1-41 
FrameRect function, (vol. 1) 1-31, 4-143 
FrameRgn function, (vol. 1) 2-21, 4-143 
FreeLibrary function, (vol. 1) 3-2, 4-144 
FreeModule function, (vol. 1) 3-2, 4-144 
FreeProcInstance function, (vol. 1) 3-2, 4-145 
FreeResource function, (vol. 1) 3-7, 4-145 
FreeSelector function, (vol. 1) 3-5, 4-146 
Function macros, Cmacro, (vol. 2) 13-8 
Function register, (vol. 2) 13-8 
Functions 

additional, (vol. 1) 1-67 

bitmap, (vol. 1) 2-25 to 2-27 

bounding rectangles, (vol. 1) 2-25 

callback, (vol. 2) 13-5 

caret, (vol. 1) 1-60 to 1-61 

clipboard, (vol. 1) 1-58 

clipping, (vol. 1) 2-22 

coordinates, (vol. 1) 2-20, 2-23 

defining in assembly language, (vol. 2) 14-4 

device context attributes, (vol. 1) 2-3 

device contexts, (vol. 1) 2-2 

displaying, (vol. 1) 1-28 

drawing tools, (vol. 1) 2-5 

entry point, (vol. 2) 14-2 

environment, (vol. 1) 2-47 

error, (vol. 1) 1-59 

exit point, (vol. 2) 14-3 

far, (vol. 2) 14-5 

filters, (vol. 1) 1-63 

font, (vol. 1) 2-28 

hardware, (vol. 1) 1-30 

hook, (vol. 1) 1-63 

information, (vol. 1) 1-57 

input, (vol. 1) 1-29 

main loop, (vol. 1) 1-4 

mapping drawing attributes, (vol. 1) 2-15 

menu, (vol. 1) 1-56 

metafile, (vol. 1) 2-41 

movement, (vol. 1) 1-28 

near, (vol. 2) 14-5 

obtaining device information, (vol. 1) 2-5 

painting, (vol. 1) 1-31 

printer control, (vol. 1) 2-44 

property lists, (vol. 1) 1-65, 1-67 

public, (vol. 2) 14-5 

rectangle 

coordinates, (vol. 1) 1-67 

specifying, (vol. 1) 1-67 
regions, (vol. 1) 2-21 
system, (vol. 1) 1-58 
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text, (vol. 1) 2-27 
window, (vol. 1) 1-6 


G 


GCL_MENUNAME option, (vol. 1) 4-368 
GCL_WNDPROC option, (vol. 1) 4-154, 4-368 
GCW_CBCLSEXTRA option, (vol. 1) 4-155, 4-369 


GCW_CBWNDEXTRA option, (vol. 1) 4-155, 4-369 


GCW_HBRBACKGROUND option, (vol. 1) 4-155, 
4-369 
GCW_HCURSOR option, (vol. 1) 4-155, 4-369 
GCW_HICON option, (vol. 1) 4-155, 4-369 
GCW_HMODULE option, (vol. 1) 4-155 
GCW_STYLE option, (vol. 1) 4-155, 4-369 
GDI functions 
brushes, predefined, (vol. 1) 2-7 
color palettes, (vol. 1) 2-10 
drawing attribute functions 
background mode and color, (vol. 1) 2-14 
described, (vol. 1) 2-13 
mapping funtions, (vol. 1) 2-15 
stretch mode and text color, (vol. 1) 2-14 
drawing tool functions, (vol. 1) 2-5 
mapping functions, (vol. 1) 2-15 
mapping modes 
constraining, (vol. 1) 2-17 to 2-18 
transformation equations, (vol. 1) 2-18 
obtaining device information, (vol. 1) 2-5 
pens, predefined, (vol. 1) 2-8 
selecting fonts, (vol. 1) 2-36 
using drawing tools, (vol. 1) 2-6 
working with color palettes, (vol. 1) 2-11 
GetActiveWindow function, (vol. 1) 1-29, 4-147 
GetAspectRatioFilter function, (vol. 1) 2-36, 4-147 
GetAsyncKeyState function, (vol. 1) 1-30, 4-147 
GetAtomHandle function, (vol. 1) 3-9, 4-148 
GetAtomName function, (vol. 1) 3-9, 4-148 
GetBitmapBits function, (vol. 1) 2-25, 4-149 
GetBitmapDimension function, (vol. 1) 2-25, 4-149 
GetBkColor function, (vol. 1) 2-14, 4-150 
GetBkMode function, (vol. 1) 2-14, 4-150 
GetBrushOrg function, (vol. 1) 2-6, 4-150 
GetB Value function, (vol. 1) 2-9, 4-151 
GetCapture function, (vol. 1) 1-29, 4-151 
GetCaretBlinkTime function, (vol. 1) 1-60, 4-151 
GetCaretPos function, (vol. 1) 1-60, 4-152 
GetCharWidth function, (vol. 1) 2-28, 4-152 
GetClassInfo function, (vol. 1) 1-7, 4-153 
GetClassLong function, (vol. 1) 1-7, 4-153 
GetClassName function, (vol. 1) 1-7, 4-154 
GetClassWord function, (vol. 1) 1-7, 4-155 
GetClientRect function, (vol. 1) 1-28, 4-156 


GetClipboardData function, (vol. 1) 1-59, 4-156 
GetClipboardFormatName function, (vol. 1) 1-59, 4-157 
GetClipboardOwner function, (vol. 1) 1-59, 4-157 
GetClipboard Viewer function, (vol. 1) 1-59, 4-158 
GetClipBox function, (vol. 1) 2-22, 4-158 
GetCodeHandle function, (vol. 1) 3-2, 4-159 
GetCodelInfo function, (vol. 1) 3-5, 4-159 to 4-160 
GETCOLORTABLE printer escape, (vol. 2) 12-21 
GetCommError function, (vol. 1) 3-11, 4-161 
GetCommEventMask function, (vol. 1) 3-11, 4-162 
GetComm/State function, (vol. 1) 3-11, 4-162 
GetCurrentPDB function, (vol. 1) 3-7, 4-163 
GetCurrentPosition function, (vol. 1) 4-163 
GetCurrentTask function, (vol. 1) 3-7, 4-164 
GetCurrentTime function, (vol. 1) 1-29, 1-58, 4-164 
GetCursorPos function, (vol. 1) 1-62, 4-164 

GetDC function, (vol. 1) 1-31, 4-165 

GetDCOrg function, (vol. 1) 2-2, 4-165 
GetDesktopWindow function, (vol. 1) 4-166 
GetDeviceCaps function, (vol. 1) 4-166 to 4-169 
GetDialogBaseUnits function, (vol. 1) 1-44, 1-47, 4-170, 
4-304, 6-28, 6-44, (vol. 2) 7-35, 8-14, 8-21 to 8-30, 8-32 
to 8-35 

GetDIBits function, (vol. 1) 2-13, 2-26, 4-168, 4-171 
GetDlgCtrlID function, (vol. 1) 1-44, 4-172 
GetDlgItem function, (vol. 1) 1-44, 4-173 
GetDlgItemInt function, (vol. 1) 1-44, 4-173 
GetDlgItemText function, (vol. 1) 1-44, 4-174 
GetDOSEnvironment function, (vol. 1) 3-7, 4-175 
GetDoubleClickTime function, (vol. 1) 1-29, 4-175 
GetDriveType function, (vol. 1) 3-13, 4-175 
GetEnvironment function, (vol. 1) 2-47, 4-176 
GETEXTENDEDTEXTMETRICS printer escape, (vol. 
2) 12-21 to 12-25 

GETEXTENTTABLE printer escape, (vol. 2) 12-26 
GETFACENAME printer escape, (vol. 2) 12-27 
GetFocus function, (vol. 1) 1-29, 4-177 
GetFreeSpace function, (vol. 1) 3-3, 4-177 
GetGValue function, (vol. 1) 2-9, 4-178 
GetInputState function, (vol. 1) 1-30, 4-178 
GetInstanceData function, (vol. 1) 3-2, 4-178 
GetKBCodePage function, (vol. 1) 1-31, 4-179 
GetKeyboardState function, (vol. 1) 1-30, 4-180 
GetKeyboardType function, (vol. 1) 4-181 
GetKeyNameText function, (vol. 1) 1-30, 4-182 
GetKeyState function, (vol. 1) 1-30, 4-183 
GetLastActivePRopup function, (vol. 1) 1-7, 4-183 
GetMapMode function, (vol. 1) 2-15, 4-184 
GetMenu function, (vol. 1) 1-56, 4-184 
GetMenuCheckMarkDimensions function, (vol. 1) 1-56, 
4-184 

GetMenultemCount function, (vol. 1) 1-56, 4-185 
GetMenultemID function, (vol. 1) 1-56, 4-185 
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GetMenuState function, (vol. 1) 1-56, 4-185 to 4-186 
GetMenuString function, (vol. 1) 1-56, 4-187 
GetMessage function, (vol. 1) 1-2, 4-188 
GetMessagePos function, (vol. 1) 1-2, 4-189 
GetMessageTime function, (vol. 1) 1-2, 4-189 
GetMetaFile function, (vol. 1) 2-41, 4-190 
GetMetaFileBits function, (vol. 1) 2-41, 4-190 
GetModuleFileName function, (vol. 1) 3-2, 4-190 
GetModuleHandle function, (vol. 1) 3-2, 4-191 
GetModuleUsage function, (vol. 1) 3-2, 4-191 
GetNearestColor function, (vol. 1) 2-9, 4-192 
GetNearestPaletteIndex function, (vol. 1) 2-10, 4-192 
GetNextDlgGrouplItem function, (vol. 1) 1-44, 4-192 
GetNextDlgTablItem function, (vol. 1) 1-44, 4-193 
GetNextWindow function, (vol. 1) 1-58, 4-194 
GetNumTasks function, (vol. 1) 3-7, 4-194 

GetObject function, (vol. 1) 2-6, 4-195 
GETPAIRKERNTABLE printer escape, (vol. 2) 12-27 to 
12-28 

GetPaletteEntries function, (vol. 1) 2-10, 4-195 
GetParent function, (vol. 1) 1-58, 4-196 
GETPHYSPAGESIZE printer escape, (vol. 2) 12-29 
GetPixel function, (vol. 1) 2-26, 4-196 
GetPolyFillMode function, (vol. 1) 2-14, 4-197 
GETPRINTINGOFFSET printer escape, (vol. 2) 12-29 
GetPriorityClipboardFormat function, (vol. 1) 1-59, 4-197 
GetPrivateProfileInt function, (vol. 1) 3-10, 4-198 to 
4-199 , 
GetPrivateProfileString function, (vol. 1) 3-10, 4-199 to 
4-200 

GetProcAddress function, (vol. 1) 3-2, 4-200 
GetProfileInt function, (vol. 1) 3-10, 4-201 
GetProfileString function, (vol. 1) 3-10, 4-202 

GetProp function, (vol. 1) 1-65, 4-203 

GetRgnBox function, (vol. 1) 2-21, 4-203 

GetROP2 function, (vol. 1) 2-14, 4-204 

GetR Value function, (vol. 1) 2-9, 4-204 
GETSCALINGFACTOR printer escape, (vol. 2) 12-30 
GetScrollPos function,.(vol. 1) 1-53, 4-205 
GetScrollRange function, (vol. 1) 1-53, 4-205 to 4-206 
GETSETPAPERBINS printer escape, (vol. 2) 12-30 to 
12-31 

GETSETPAPERMETRICS printer escape, (vol. 2) 12-32 
GETSETPAPERORIENT printer escape, (vol. 2) 12-32 
GETSETPAPERORIENTATION printer escape, (vol. 2) 
12-33 ; 

GETSETSCREENPARAMS printer escape, (vol. 2) 
12-33 to 12-34 , 
GetStockObject function, (vol. 1) 2-6, 4-207 
GetStretchBltMode function, (vol. 1) 2-14, 4-208 
GetSubMenu function, (vol. 1) 1-56, 4-209, (vol. 2) 7-17 
GetSysColor function, (vol. 1) 1-58, 4-209, 4-250 
GetSysModalWindow function, (vol. 1) 4-210 


GetSystemDirectory function, (vol. 1) 3-13, 4-210 
GetSystemMenu function, (vol. 1) 1-57, 4-211, 6-106 
GetSystemMetrics function, (vol. 1) 1-58, 4-212 
GetSystemPaletteEntries function, (vol. 1) 2-10, 4-213 
GetSystemPaletteUse function, (vol. 1) 2-10, 4-214 
GetTabbedTextExtent function, (vol. 1) 2-27, 4-215 
GETTECHNOLOGY printer escape, (vol. 2) 12-35 
GetTempDrive function, (vol. 1) 3-13, 4-216 
GetTempFileName function, (vol. 1) 3-13, 4-216 
GetTextAlign function, (vol. 1) 2-27, 4-217 to 4-218 
GetTextCharacterExtra function, (vol. 1) 4-219 
GetTextColor function, (vol. 1) 2-14, 4-219 
GetTextExtent function, (vol. 1) 2-27, 4-220 
GetTextFace function, (vol. 1) 2-27, 4-220 
GetTextMetrics function, (vol. 1) 2-27, 4-221 
GetThresholdEvent function, (vol. 1) 3-12, 4-221 
GetThresholdStatus function, (vol. 1) 3-12, 4-222 
GetTickCount function, (vol. 1) 1-29, 4-222 
GetTopWindow function, (vol. 1) 1-58, 4-222 
GETTRACKKERNTABLE printer escape, (vol. 2) 12-35 
to 12-36 

GetUpdateRect function, (vol. 1) 1-31, 4-223 
GetUpdateRgn function, (vol. 1) 1-31, 4-223 
GETVECTORBRUSHSIZE printer escape, (vol. 2) 12-37 
GETVECTORPENSIZE printer escape, (vol. 2) 12-37 
GetVersion function, (vol. 1) 3-2, 4-224 
GetViewportExt function, (vol. 1) 2-15, 4-225 
GetViewportOrg function, (vol. 1) 2-15, 4-225 
GetWindow function, (vol. 1) 1-58, 4-225 
GetWindowDC function, (vol. 1) 1-31, 4-226 
GetWindowExt function, (vol. 1) 2-15, 4-227 
GetWindowLong function, (vol. 1) 1-7, 1-16, 4-228 
GetWindowOrg function, (vol. 1) 2-15, 4-228 
GetWindowRect function, (vol. 1) 1-28, 4-229 
GetWindowsDirectory function, (vol. 1) 3-13, 4-229 
GetWindowTask function, (vol. 1) 1-58, 4-230 
GetWindowText function, (vol. 1) 1-28, 4-230 
GetWindowTextLength function, (vol. 1) 1-29, 4-231 
GetWindow Word function, (vol. 1) 1-7, 4-231 
GetWinFlags function, (vol. 1) 3-3, 4-232 
GetWinMem32Version, (vol. 2) E-3, E-10 

Global variable, Cmacro, (vol. 2) 14-11 
Global16PointerAlloc function, (vol. 2) E-3, E-10 to E-11 
Global16PointerFree function, (vol. 2) E-3, E-11 
Global32Alloc function, (vol. 2) E-3, E-12 to E-13 
Global32CodeAlias function, (vol. 2) E-3, E-13 to E-14 
Global32CodeAliasFree function, (vol. 2) E-3, E-14 
Global32Free function, (vol. 2) E-3, E-14 to E-15 
Global32Realloc function, (vol. 2) E-3, E-15 
GlobalAddAtom function, (vol. 1) 3-9, 4-233 
GlobalAlloc function, (vol. 1) 3-3, 4-233 to 4-234 
GlobalCompact function, (vol. 1) 3-3, 4-177, 4-235 
GlobalDeleteAtom function, (vol. 1) 3-9, 4-235 
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GlobalDiscard function, (vol. 1) 3-3, 4-236 GWL_EXSTYLE option, (vol. 1) 4-228, 4-416 
GlobalDosAlloc function, (vol. 1) 3-3, 4-236 GWL_STYLE option, (vol. 1) 4-228, 4-416 
GlobalDosFree function, (vol. 1) 3-3, 4-237 GWL_WNDPROC option, (vol. 1) 4-228, 4-416 
GlobalFindAtom function, (vol. 1) 3-10, 4-237 GWW_HINSTANCE option, (vol. 1) 4-231, 4-428 
GlobalFix function, (vol. 1) 3-5, 4-238 GWW_HWNDPARENT option, (vol. 1) 4-231 
GlobalFlags function, (vol. 1) 3-3, 4-238 GWW_ID option, (vol. 1) 4-231, 4-428 
GlobalFree function, (vol. 1) 3-3, 4-239 
GlobalGetAtomName function, (vol. 1) 3-10, 4-240 H 
GLOBALHANDLE data type, (vol. 2) 7-2 HANDLE data type, (vol. 2) 7-2 
GlobalHandle function, (vol. 1) 3-3, 4-240 Handle table, (vol. 2) 7-38 
GlobalLock function, (vol. 1) 3-3, 4-241 Handles 
GlobalLRUNewest function, (vol. 1) 3-3, 4-241 instance, (vol. 1) 1-12 
GlobalLRUOldest function, (vol. 1) 3-3, 4-242 task, obtaining, (vol. 1) 4-164 
GlobalNotify function, (vol. 1) 3-3, 4-242 HANDLETABLE data structure, (vol. 2) 7-38 
GlobalPageLock function, (vol. 1) 3-6, 4-243 HBITMAP data type, (vol. 2) 7-2 
GlobalPageUnlock function, (vol. 1) 3-6, 4-244 HBRUSH data type, (vol. 2) 7-2 
GlobalReAlloc function, (vol. 1) 3-3, 4-244 to 4-245 HCURSOR data type, (vol. 2) 7-2 
GlobalSize function, (vol. 1) 3-3, 4-246 HDC data type, (vol. 2) 7-2 
GlobalUnfix function, (vol. 1) 3-6, 4-247 Heap, local, (vol. 2) 10-5 
GlobalUnlock function, (vol. 1) 3-4, 4-247 HEAPSIZE module-definition statement, (vol. 2) 10-5 
GlobalUnwire function, (vol. 1) 3-4, 4-248 HEAPSIZE statement 
GlobalWire function, (vol. 1) 3-4, 4-248 described, (vol. 2) 10-1 
globalX macro, Cmacro, (vol. 2) 14-10 syntax, (vol. 2) 10-5 
GMEM_DDESHARE option, (vol. 1) 4-234, 4-239 Help application, (vol. 1) 4-460 
GMEM_DISCARDABLE option, (vol. 1) 4-234, 4-239, HELP_CONTEXT option, (vol. 1) 4-460 
4-245 HELP_HELPONHELP option, (vol. 1) 4-460 
GMEM_DISCARDED option, (vol. 1) 4-239 HELP_INDEX option, (vol. 1) 4-460 
GMEM_FIXED option, (vol. 1) 4-234 HELP_KEY option, (vol. 1) 4-461 
GMEM_MODIFY option, (vol. 1) 4-245 HELP_MULTIKEY option, (vol. 1) 4-461 
GMEM_MOVEABLE option, (vol. 1) 4-234, 4-245 HELP option, MENUITEM resource statement, (vol. 2) 
GMEM_NOCOMPACT option, (vol. 1) 4-234, 4-246 8-10 
GMEM_NODISCARD option, (vol. 1) 4-234, 4-246 HELP_QUIT option, (vol. 1) 4-461 
GMEM_NOT_BANKED option, (vol. 1) 4-177, 4-234, HELP_SETINDEX, (vol. 1) 4-461 
4-239 HFONT data type, (vol. 2) 7-2 
GMEM_NOTIFY option, (vol. 1) 4-234 HIBYTE utility macro, (vol. 1) 3-13, 4-252 
GMEM_ZEROINIT option, (vol. 1) 4-234, 4-246 HICON data type, (vol. 2) 7-2 
Graphics device interface, defined, (vol. 1) xvii HideCaret function, (vol. 1) 1-60, 4-252 
GRAY_BRUSH stock object, (vol. 1) 4-207 HiliteMenultem function, (vol. 1) 1-57, 4-253 
GRAYED menu-item option, (vol. 2) 7-51 HIWORD utility macro, (vol. 1) 3-13, 4-171, 4-254 
GRAYED option HMENU data type, (vol. 2) 7-2 
MENUITEM resource statement, (vol. 2) 8-11 HOLLOW_BRUSH stock object, (vol. 1) 4-207 
POPUP resource statement, (vol. 2) 8-12 Hook chain, (vol. 1) 4-82 
GrayString function, (vol. 1) 1-31, 4-249 to 4-251 Hook function, (vol. 1) 4-82 
Group box, BUTTON class, (vol. 2) 8-27 HORZRES device capability, (vol. 1) 4-167 
GROUPBOX resource statement HORZSIZE device capability, (vol. 1) 4-167 
described, (vol. 2) 8-27 to 8-28 HPALETTE data type, (vol. 2) 7-2 
DIALOG resource statement, (vol. 2) 8-20 HPEN data type, (vol. 2) 7-2 
GW_CHILD option, (vol. 1) 4-226 HRGN data type, (vol. 2) 7-2 
GW_HWNDFIRST option, (vol. 1) 4-226 HS_BDIAGONAL brush hatch style, (vol. 1) 4-52, (vol. 
GW_HWNDLAST option, (vol. 1) 4-226 2) 7-40 
GW_HWNDNEXT option, (vol. 1) 4-194, 4-226 HS_CROSS brush hatch style, (vol. 1) 4-52, (vol. 2) 7-40 
GW_HWNDPREV option, (vol. 1) 4-194, 4-226 HS_DIAGCROSS brush hatch style, (vol. 1) 4-52, (vol. 


GW_OWNER option, (vol. 1) 4-226 
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2) 7-40 
HS_FDIAGONAL brush hatch style, (vol. 1) 4-52, 2, (vol. 
2) 7-40 


HS_HORIZONTAL brush hatch style, (vol. 1) 4-52, (vol. 


2) 7-40 

HS_VERTICAL brush hatch style, (vol. 1) 4-52, (vol. 2) 
7-40 

HSTR data type, (vol. 2) 72 

HTBOTTOM mouse-position code, (vol. 1) 6-85 
HTBOTTOMLEFT mouse-position code, (vol. 1).6-85 
HTBOTTOMRIGHT mouse-position code, (vol. 1) 6-85 
HTCAPTION mouse-position code, (vol. 1) 6-85 
HTCLIENT mouse-position code, (vol. 1) 6-85 
HTERROR mouse-position code, (vol. 1) 6-85 
HTGROWBOX mouse-position code, (vol. 1) 6-85 
HTHSCROLL mouse-position code, (vol. 1) 6-85 
HTLEFT mouse-position code, (vol. 1) 6-85 
HTMENU mouse-position code, (vol. 1) 6-85 
HTNOWHERE mouse-position code, (vol. 1) 6-85 
HTREDUCE mouse-position code, (vol. 1) 6-85 
HTRIGHT mouse-position code, (vol. 1) 6-85 
HTSIZE mouse-position code, (vol. 1) 6-85 
HTSYSMENU mouse-position code, (vol. 1) 6-85 
HTTOP mouse-position code, (vol. 1) 6-85 
HTTOPLEFT mouse-position code, (vol. 1) 6-85 
HTTOPRIGHT mouse-position code, (vol. 1) 6-86 
HTTRANSPARENT mouse-position code, (vol. 1) 6-86 
HTVSCROLL mouse-position code, (vol. 1) 6-86 
HTZOOM mouse-position code, (vol. 1) 6-86 
hWindowMenu, (vol. 2) 7-17 


/ 


IBM PC extended character set, (vol. 2) D-1 
Icon 

class, (vol. 1) 1-12 

drawing, (vol. 1) 1-39 

file format, (vol. 2) 9-2 
Icon resource, (vol. 2) 8-2 
ICON resource-compiler key word, (vol. 2) 8-2 
ICON resource statement 

described, (vol. 2) 8-33 

DIALOG resource statement, (vol. 2) 8-20 
IDABORT menu-item value, (vol. 1) 4-307 
IDC_ARROW cursor type, (vol. 1) 4-278 
IDC_CROSS cursor type, (vol. 1) 4-278 
IDC_IBEAM cursor type, (vol. 1) 4-278 
IDC_ICON cursor type, (vol. 1) 4-278 
IDC_SIZE, (vol. 1) 4-278 
IDC_SIZENESW cursor type, (vol. 1) 4-278 
IDC_SIZENS cursor type, (vol. 1) 4-278 
IDC_SIZENWSE cursor type, (vol. 1) 4-278 
IDC_SIZEWE cursor type, (vol. 1) 4-278 


IDC_UPARROW cursor type, (vol. 1) 4-278 
IDC_WAIT cursor type, (vol. 1) 4-278 

IDCANCEL menu-item value, (vol. 1) 4-132, 4-307 
IDI_APPLICATION icon type, (vol. 1) 4-279 
IDI_ASTERISK icon type, (vol. 1) 4-279 
IDI_EXCLAMATION icon type, (vol. 1) 4-279 
IDI_HAND icon type, (vol. 1) 4-279 
IDI_QUESTION icon type, (vol. 1) 4-279 
IDIGNORE mentu-item value, (vol. 1) 4-307 

IDNO menu-item value, (vol. 1) 4-307 

IDOK menu-item value, (vol. 1) 4-132, 4-307 
IDRETRY mentu-item value, (vol. 1) 4-307 

IDYES menu-item value, (vol. 1) 4-307 

IE_BADID error return value for OpenComm function, 
(vol. 1) 4-322 

IE_BAUDRATE error return value for Sen iomm 
function, (vol. 1) 4-322 

IE_BYTESIZE error return value for OpenComm 
function, (vol. 1) 4-322 

IE_DEFAULT error return value for OpenComm 
function, (vol. 1) 4-322 

IE_HARDWARE error return value for OpenComm 
function, (vol. 1) 4-322 

TE_MEMORY error return value for OpenComm 
function, (vol. 1) 4-322 

IE_NOPEN error return value for OpenComm function, 
(vol. 1) 4-322 

TE_OPEN error return value for OpenComm function, 
(vol. 1) 4-322 

#if directive, resource compiler, (vol. 2) 8-49 

#ifdef directive, resource compiler, (vol. 2) 8-48 
#ifndef directive, resource compiler, (vol. 2) 8-49 


_ IMPORTS module-definition statement, (vol. 2) 10-6 


IMPORTS statement, (vol. 2) 10-1, 10-6 
INACTIVE option 

MENUITEM resource statement, (vol. 2) 8-10 

POPUP resource statement, (vol. 2) 8-11 
INCLUDE command, Cmacro, (vol. 2) 13-4 
#include directive 

resource compiler, (vol. 2) 8-47 

when required with STYLE statement, (vol. 2) 8-15 
INCLUDE environmental variable, (vol. 2) 8-47 
IncUpdate, (vol. 2) 7-55 
InflateRect function, (vol. 1) 1-67 to 1-68, 4-255 
InitAtomTable function, (vol. 1) 3-10, 4-255 
Initialization file, application-specific 

getting integer from, (vol. 1) 4-199 

getting string from, (vol. 1) 4-199 

writing to, (vol. 1) 4-463 
InSendMessage function, (vol. 1) 1-2, 4-256 
InsertMenu function, (vol. 1) 1-26, 1-57, 4-54, 4-59, 
4-211, 4-256 to 4-258, 6-106, (vol. 2) 7-38 
Instructions, coding sequences, (vol. 2) 13-9 
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int data type, (vol. 2) 7-2 
Integer messages, (vol. 1) 6-1 
Intercharacter spacing, default, (vol. 1) 1-33 
Internal data structures, (vol. 1) 1-16 
Interrupt 
function request (21H), (vol. 1) 4-104 
-function request (5CH), (vol. 1) 4-315 
IntersectClipRect function, (vol. 1) 2-22, 4-259 
IntersectRect function, (vol. 1) 1-67 to 1-68, 4-260 
InvalidateRect function, (vol. 1) 1-31, 4-261 
InvalidateRgn function, (vol. 1) 1-32, 4-261 
InvertRect function, (vol. 1) 1-32, 4-262 
InvertRgn function, (vol. 1) 2-21, 4-263 
IsCharAlpha function, (vol. 1) 3-8, 4-263 
IsCharAlphaNumeric function, (vol. 1) 3-8, 4-264 
IsCharLower function, (vol. 1) 3-8, 4-264 
IsCharUpper function, (vol. 1) 3-8, 4-264 
IsChild function, (vol. 1) 1-58, 4-265 
IsClipboardFormatAvailable function, (vol. 1) 1-59, 4-265 
IsDialogMessage function, (vol. 1) 1-44, 4-266 
IsDlgButtonChecked function, (vol. 1) 1-44, 4-266 
IsIconic function, (vol. 1) 1-29, 4-267 
IsRectEmpty function, (vol. 1) 1-68, 4-267 
IsWindow function, (vol. 1) 1-58, 4-268 
IsWindowEnabled function, (vol. 1) 1-30, 4-268 
IsWindow Visible function, (vol. 1) 1-29, 4-269 
IsZoomed function, (vol. 1) 1-29, 4-269 


K 


Key 
BACKSPACE, (vol. 2) 8-36 
CONTROL, (vol. 2) 8-8 
editing, (vol. 2) 8-30 
getting name, (vol. 1) 4-182 
SHIFT, (vol. 2) 8-8 
TAB, (vol. 2) 8-17 
Key word, resource-compiler 
BITMAP, (vol. 2) 8-2 
CURSOR, (vol. 2) 8-2 
DISCARDABLE, (vol. 2) 8-2, 8-4 to 8-6, 8-9, 8-14 
FIXED, (vol. 2) 8-2 to 8-3, 8-5 to 8-6, 8-9, 8-13 
FONT, (vol. 2) 8-2 
ICON, (vol. 2) 8-2 
LOADONCALL, (vol. 2) 8-2 to 8-3, 8-5 to 8-6, 8-9, 8-13 
MOVEABLE, (vol. 2) 8-2, 8-4 to 8-6, 8-9, 8-14 
PRELOAD, (vol. 2) 8-2 to 8-4, 8-6, 8-9, 8-13 
Keyboard, using with dialog boxes, (vol. 1) 1-52 
‘KillTimer function, (vol. 1) 1-30, 4-270 


L 


Label 
name, (vol. 2) 14-4, 14-6 


public, (vol. 2) 13-7 
labelX macro, Cmacro, (vol. 2) 14-11 
Language, assembly, (vol. 2) 13-1 
LB_ADDSTRING message, (vol. 1) 5-12, 6-34 to 6-35, 
6-39, 6-41, (vol. 2) 7-27, 7-38, 7-49 
LB_DELETESTRING message, (vol. 1) 5-12, 6-34, 6-57 
LB_DIR message, (vol. 1) 5-12, 6-35 
LB_FINDSTRING message, (vol. 1) 5-12, 6-35 
LB_GETCOUNT message, (vol. 1) 5-12, 6-36 
LB_GETCURSEL message, (vol. 1) 5-12, 6-36 
LB_GETHORIZONTALEXTENT message, (vol. 1) 
5-12, 6-36 
LB_GETITEMDATA message, (vol. 1) 5-12, 6-37 
LB_GETITEMRECT message, (vol. 1) 5-12, 6-37 
LB_GETSEL message, (vol. 1) 5-12, 6-37 
LB_GETSELCOUNT message, (vol. 1) 5-12, 6-38 
LB_GETSELITEMS message, (vol. 1) 5-12, 6-38 
LB_GETTEXT message, (vol. 1) 5-12, 6-38 
LB_GETTEXTLEN message, (vol. 1) 5-12, 6-39 
LB_GETTOPINDEX message, (vol. 1) 5-12, 6-39 
LB_INSERTSTRING message, (vol. 1) 5-12, 6-34 to 
6-35, 6-39 to 6-41, (vol. 2) 7-27, 7-38, 7-49 
LB_RESETCONTENT message, (vol. 1) 5-13, 6-40, 6-57 
LB_SELECTSTRING message, (vol. 1) 5-13, 6-40 
LB_SELITEMRANGE message, (vol. 1) 5-13, 6-41 
LB_SETCOLUMNWIDTH message, (vol. 1) 4-72, 5-13, 
6-42, (vol. 2) 8-42 
LB_SETCURSEL message, (vol. 1) 5-13, 6-42 
LB_SETHORIZONTALEXTENT message, (vol. 1) 
5-13, 6-42 
LB_SETITEMDATA message, (vol. 1) 5-13, 6-37, 6-43 
LB_SETSEL message, (vol. 1) 5-13, 6-43 
LB_SETTABSTOPS message, (vol. 1) 5-13, 6-44 
LB_SETTOPINDEX message, (vol. 1) 5-13, 6-44 
LBN_DBLCLK message, (vol. 1) 5-16, 6-45 
LBN_ERRSPACE message, (vol. 1) 5-16, 6-45 
LBN_KILLFOCUS message, (vol. 1) 5-16, 6-45 
LBN_SELCHANGE message, (vol. 1) 5-16, 6-46 
LBN_SETFOCUS message, (vol. 1) 5-16, 6-46 
LBS_EXTENDEDSEL control style, (vol. 1) 4-71, (vol. 
2) 8-42 
LBS_HASSTRINGS control style, (vol. 1) 4-72, 6-34 to 
6-35, 6-37, 6-39 to 6-41, (vol. 2) 8-42 
LBS_MULTICOLUMN control style, (vol. 1) 4-72, 6-42, 
(vol. 2) 8-42 
LBS_MULTIPLESEL control style, (vol. 1) 4-72, (vol. 
2) 8-42 
LBS_NOINTEGRALHEIGHT control style, (vol. 2) 8-42 
LBS_NOREDRAW control style, (vol. 1) 4-72, (vol. 2) 
8-42 
LBS_NOTIFY control style, (vol. 1) 4-72, (vol. 2) 8-42 
LBS_OWNERDRAWFIXED control style, (vol. 1) 4-72, 
(vol. 2) 8-42 
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LBS_OWNERDRAWVARIABLE control style, (vol. 1) 
4-72, (vol. 2) 8-42 
LBS_SORT control style, (vol. 1) 4-72, (vol. 2) 8-42 
LBS_STANDARD control style, (vol. 1) 4-72, (vol. 2) 
8-41 
LBS_WANTKEYBOARDINPUT control style, (vol. 2) 
8-43 
_Iclose function, (vol. 1) 3-14, 4-271 
_Icreat function, (vol. 1) 3-14, 4-271 
Library 
C-language, (vol. 2) 13-5 
linking, (vol. 2) 13-5 
Windows, (vol. 2) 13-5 
Library module, (vol. 2) 10-7 
LIBRARY module-definition statement, (vol. 2) 10-7 
LIBRARY statement, (vol. 2) 10-1, 10-7 
LimitEMSPages function, (vol. 1) 3-4, 4-272 
Line-output functions 
coordinates, (vol. 1) 2-23 
pen styles, colors and widths, (vol. 1) 2-23 
LINECAPS device capability, (vol. 1) 4-169 
LineDDA function, (vol. 1) 2-22, 4-272 
LineTo function, (vol. 1) 2-22, 4-273 
List box 
directory listings, (vol. 1) 1-49 
horizontal scrolling, (vol. 1) 6-36, 6-42 
owner-draw, (vol. 1) 1-50, (vol. 2) 7-26 
deleted item, (vol. 1) 6-57 
measuring, (vol. 2) 7-48 
sorting, (vol. 1) 6-53, (vol. 2) 7-19 
tab stops in, (vol. 1) 6-44 
LISTBOX control class 
control styles, (vol. 2) 8-26, 8-41 
described, (vol. 1) 4-65, (vol. 2) 8-26, 8-36 
LISTBOX resource statement 
described, (vol. 2) 8-26 
DIALOG resource statement, (vol. 2) 8-20 
_llseek function, (vol. 1) 3-14, 4-274 
LMEM_DISCARDABLE option, (vol. 1) 4-285, 4-287, 
4-290 
LMEM_DISCARDED option, (vol. 1) 4-287 
LMEM_FIXED option, (vol. 1) 4-285 
LMEM_MODIFY option, (vol. 1) 4-285, 4-290 
LMEM_MOVEABLE option, (vol. 1) 4-285, 4-290 
LMEM_NOCOMPACT option, (vol. 1) 4-285, 4-290 
LMEM_NODISCARD option, (vol. 1) 4-286, 4-291 
LMEM_ZEROINIT option, (vol. 1) 4-286, 4-291 
LoadAccelerators function, (vol. 1) 3-7, 4-275 
LoadBitmap function, (vol. 1) 2-26, 3-7, 4-275 to 4-276 
LoadCursor function, (vol. 1) 1-62, 3-7, 4-277 
LoadlIcon function, (vol. 1) 3-7, 4-278 
LoadLibrary function, (vol. 1) 3-2, 4-279 
LoadMenu function, (vol. 1) 3-7, 4-280 


LoadMenulIndirect function, (vol. 1) 1-57, 4-281 
LoadModule function, (vol. 1) 3-15, 4-281 to 4-282 
LOADONCALL resource-compiler key word, (vol. 2) 
8-2 to 8-3, 8-5 to 8-6, 8-9, 8-13 
LoadResource function, (vol. 1) 3-7, 4-283 
LoadString function, (vol. 1) 3-7, 4-284, (vol. 2) 8-5 
LOBYTE utility macro, (vol. 1) 3-13, 4-285 
Local heap, (vol. 2) 10-5 
Local stack, (vol. 2) 10-9 
LocalAlloc function, (vol. 1) 3-4, 4-285 
LocalCompact function, (vol. 1) 3-4, 4-286 
LocalDiscard function, (vol. 1) 3-4, 4-287 
LocalFlags function, (vol. 1) 3-4, 4-287 
LocalFree function, (vol. 1) 3-4, 4-288 
LOCALHANDLE data type, (vol. 2) 7-3 
LocalHandle function, (vol. 1) 3-4, 4-288 
LocalInit function, (vol. 1) 3-4, 4-288 
LocalLock function, (vol. 1) 3-4, 4-289 
LocalReAlloc function, (vol. 1) 3-4, 4-290 
LocalShrink function, (vol. 1) 3-4, 4-291 
LocalSize function, (vol. 1) 3-4, 4-292 
LocalUnlock function, (vol. 1) 3-4, 4-292 
localX, Cmacro, (vol. 2) 13-9, 14-11 
LockData function, (vol. 1) 3-4, 4-293 
LockResource function, (vol. 1) 3-7, 4-293 
LockSegment function, (vol. 1) 3-4, 3-6, 4-294 
LOGBRUSH data structure, (vol. 2) 7-39 
LOGFONT data structure, (vol. 2) 7-40 to 7-44 
Logical palette 

See also LOGPALETTE data structure 

and input focus, (vol. 1) 6-95 

changed, (vol. 1) 6-92 

changing entries in, (vol. 1) 4-387 

creating, (vol. 1) 4-55, (vol. 2) 7-45 

finding color in, (vol. 1) 4-192 

index specifier (direct), (vol. 1) 4-327 

index specifier (indirect), (vol. 1) 4-328 

realizing, (vol. 1) 4-343, 6-92 

retrieving entries, (vol. 1) 4-195 

selecting, (vol. 1) 4-361 
LOGPALETTE data structure, (vol. 1) 4-55, (vol. 2) 
7-45, 7-55. 
LOGPEN data structure, (vol. 2) 7-45 to 7-46 
LOGPIXELSX device capability, (vol. 1) 4-167 
LOGPIXELSY device capability, (vol. 1) 4-167 
long data type, (vol. 2) 7-3 
_lopen function, (vol. 1) 3-14, 4-294 to 4-295 
LOWORD utility macro, (vol. 1) 3-13, 4-171, 4-296 
LPBITMAP data type, (vol. 2) 7-3 
LPBITMAPCOREHEADER data type, (vol. 2) 7-3 
LPBITMAPCOREINFO data type, (vol. 2) 7-3 
LPBITMAPFILEHEADER data type, (vol. 2) 7-3 
LPBITMAPINFO data type, (vol. 2) 7-3 
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LPBITMAPINFOHEADER data type, (vol. 2) 7-3 
LPCOMPAREITEMSTRUCT data type, (vol. 2) 7-3 
LPCREATESTRUCT data type, (vol. 2) 7-3 
LPDELETEITEMSTRUCT data type, (vol. 2) 7-3 
LPDRAWITEMSTRUCT data type, (vol. 2) 7-3 
LPHANDLETABLE data type, (vol. 2) 7-3 
LPINT data type, (vol. 2) 7-3 
LPLOGBRUSH data type, (vol. 2) 7-3 
LPLOGFONT data type, (vol. 2) 7-3 
LPLOGPALETTE data type, (vol. 2) 7-3 
LPLOGPEN data type, (vol. 2) 7-4 
LPMEASUREITEMSTRUCT data type, (vol. 2) 7-4 
LPMETAFILEPICT data type, (vol. 2) 7-4 
LPMSG data type, (vol. 2) 7-4 
LPOFSTRUCT data type, (vol. 2) 7-4 
LPPAINTSTRUCT data type, (vol. 2) 7-4 
LPPALETTEENTRY data type, (vol. 2) 7-4 
LPPOINT data type, (vol. 2) 7-4 
LPRECT data type, (vol. 2) 7-4 
LPSTR data type, (vol. 2) 7-4 
LPTEXTMETRIC data type, (vol. 2) 7-4 
LPtoDP function, (vol. 1) 2-20, 4-296 
LPVOID data type, (vol. 2) 7-4 
LPWNDCLASS data type, (vol. 2) 7-4 
_lread function, (vol. 1) 3-14, 4-297 
Istrcat function, (vol. 1) 3-8, 4-297 
Istremp function, (vol. 1) 3-8, 4-298 
Istrcmpi function, (vol. 1) 3-8, 4-299 
Istrcpy function, (vol. 1) 3-9, 4-299 
Istrlen function, (vol. 1) 3-9, 4-300 
LTEXT resource statement 

described, (vol. 2) 8-20 to 8-21 

DIALOG resource statement, (vol. 2) 8-20 
LTGRAY_BRUSH stock object, (vol. 1) 4-207 
_lwrite function, (vol. 1) 3-14, 4-300 to 4-301 


M 


Macro Assembler, (vol. 2) 13-1 

Macros, Cmacro, (vol. 2) 13-6, 14-1 
MAKEINTATOM utility macro, (vol. 1) 3-10, 3-13, 
4-302 

MAKEINTRESOURCE function, (vol. 1) 3-13 
MAKEINTRESOURCE utility macro, (vol. 1) 4-153, 
4-302 

MAKELONG utility macro, (vol. 1) 3-13, 4-302 
MAKEPOINT utility macro, (vol. 1) 3-13, 4-303 
MakeProclInstance function, (vol. 1) 3-2, 4-303, (vol. 2) 
7-1 

MapDialogRect function, (vol. 1) 1-44, 4-304 
Mapping mode, default, (vol. 1) 1-33 
MapVirtualKey function, (vol. 1) 1-31, 4-305 
MARKPARITY parity type, (vol. 2) 7-23 


max macro, (vol. 1) 4-305 
Maximize box, (vol. 2) 8-17 
MB_ABORTRETRYIGNORE option , (vol. 1) 4-308 
MB_APPLMODAL option, (vol. 1) 4-308 
MB_DEFBUTTON 1 option, (vol. 1) 4-308 
MB_DEFBUTTON2 option, (vol. 1) 4-308 
MB_DEFBUTTON3 option, (vol. 1) 4-308 
MB_ICONASTERISK option, (vol. 1) 4-308 
MB_ICONEXCLAMATION option, (vol. 1) 4-308 
MB_ICONHAND option, (vol. 1) 4-308 
MB_ICONINFORMATION option, (vol. 1) 4-308 
MB_ICONQUESTION option, (vol. 1) 4-308 
MB_ICONSTOP option, (vol. 1) 4-308 
MB_OK option, (vol. 1) 4-308 
MB_OKCANCEL option, (vol. 1) 4-308 
MB_RETRYCANCEL option, (vol. 1) 4-308 
MB_SYSTEMMODAL option, (vol. 1) 4-308 
MB_TASKMODAL option, (vol. 1) 4-309 
MB_YESNO option, (vol. 1) 4-309 
MB_YESNOCANCEL option, (vol. 1) 4-309 
MDI. See Multiple document interface (MDI) 
MDICREATESTRUCT 

as parameter of WM_MDICREATE message, (vol. 1) 
6-76 

data structure, (vol. 2) 7-47 
MEASUREITEMSTRUCT data structure, (vol. 1) 6-80, 
(vol. 2) 7-48 to 7-50 
memC option, Cmacro, (vol. 2) 13-2 
memH option, Cmacro, (vol. 2) 13-2 
memL option, Cmacro, (vol. 2) 13-2 . 
memM option, Cmacro, (vol. 2) 13-2 
MEMORY combine type, Cmacro, (vol. 2) 14-6 
Memory, least-recently used, (vol. 1) 4-241 to 4-242 
Memory model 

flat, (vol. 2) E-1 

segmented, (vol. 2) E-2 . 
Memory-model option 

Cmacro, (vol. 2) 13-2 

compact. See memC option, Cmacro 

huge. See memH option, Cmacro 

large. See memL option, Cmacro 

medium. See memM option, Cmacro 

small. See memS option, Cmacro 
memsS option, Cmacro, (vol. 2) 13-2 
Menu 

changing, (vol. 1) 4-11 to 4-13, 4-256 to 4-258, 4-309 to 
4-311 

class, (vol. 1) 1-14 

creating, (vol. 1) 4-54 

deleting, (vol. 1) 4-87 

loading, (vol. 2) 7-50 

owner-draw. See Menu, owner-draw 

pop-up, (vol. 1) 1-26, 4-59 
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resource, (vol. 2) 8-8 
Menu bar, described, (vol. 1) 1-25 
Menu checkmark 
custom, (vol. 1) 4-385 
getting size of, (vol. 1) 4-184 
Menu functions, (vol. 1) 1-56 
Menu item, removing, (vol. 1) 4-349 
Menu, owner-draw 
drawing, (vol. 2) 7-36 
measuring, (vol. 2) 7-48 
MENU resource statement, (vol. 2) 8-8 to 8-11, 8-13, 
8-18 
MENUBARBREAK option 
MENUITEM statement, (vol. 2) 8-11 
POPUP statement, (vol. 2) 8-12 
MENUBREAK option 
MENUITEM statement, (vol. 2) 8-11 
POPUP statement, (vol. 2) 8-11 
MENUITEM SEPARATOR statement, (vol. 2) 8-13 
MENUITEM statement, (vol. 2) 8-10 
MENUITEMTEMPLATE data structure, (vol. 2) 7-50 to 
7-51 
MERGECOPY raster operation, (vol. 1) 4-19 
MERGEPAINT raster operation, (vol. 1) 4-19 
Message functions, (vol. 1) 1-2 
MessageBeep function, (vol. 1) 1-59, 4-306 
MessageBox function, (vol. 1) 1-59, 4-306 to 4-308 
Messages 
application queue, (vol. 1) 1-3 
bypassing the queue, (vol. 1) 1-3 
checking the queue, (vol. 1) 1-5 
clipboard, (vol. 1) 5-7 
closing, (vol. 1) 1-28 
contents, (vol. 1) 6-1 
described, (vol. 1) 1-6 
destroy message, (vol. 1) 1-28 
dispatching, (vol. 1) 1-3 
examining - 
checking queues, passing, posting, (vol. 1) 1-6 
formatted and transmitting, (vol. 1) 1-6 
generated by applications, (vol. 1) 1-3 
generating or processing 
input events and application queue, (vol. 1) 1-3 
queuing and virtual-key, (vol. 1) 1-3 
input events, (vol. 1) 1-3 
integer, (vol. 1) 6-1 
keyboard input, (vol. 1) 1-4 
peeking, (vol. 1) 1-5 
posting, (vol. 1) 1-5, 4-335 
pulling, (vol. 1) 1-3 
pushing, (vol. 1) 1-3 
ranges, (vol. 1) 6-1 
reading, (vol. 1) 1-3, 1-5 


reserved, (vol. 1) 6-1 
sending, (vol. 1) 1-5 
special actions, (vol. 1) 1-3 
string, (vol. 1) 6-1 
translating 
accelerator keys, (vol. 1) 1-5 
described, (vol. 1) 1-4 
loops, (vol. 1) 1-5 
virtual keys, (vol. 1) 1-4 
window 
default processing, (vol. 1) 4-85 
functions, (vol. 1) 1-3 
Metafile file format, (vol. 2) 9-6 
Metafile functions 
additional escapes, (vol. 1) 2-47 
described, (vol. 1) 2-41 
environment, (vol. 1) 2-47 
information escapes, (vol. 1) 2-47 
printer escapes 
banding, (vol. 1) 2-45 to 2-46 
starting and ending, (vol. 1) 2-46 
terminating, (vol. 1) 2-46 
Metafile picture format, (vol. 2) 7-52 
METAFILEPICT data structure, (vol. 2) 7-52 
Metafiles 
changing, (vol. 1) 2-43 
creating, (vol. 1) 2-41 to 2-42 
deleting, (vol. 1) 2-43 
storing, (vol. 1) 2-43 
MF_BITMAP menu flag, (vol. 1) 4-13, 4-258, 4-311, 
6-81 
MF_BYCOMMAND menu flag, (vol. 1) 4-25, 4-112, 
4-253, 4-258, 4-311 
MF_BYPOSITION menu flag, (vol. 1) 4-25, 4-112, 
4-253, 4-258, 4-311 
MF_CHECKED menu flag, (vol. 1) 4-13, 4-25, 4-186, 
4-258, 4-311, 6-81 i, 
MF_CHECKED mentv-item option, (vol. 2) 7-51 
MF_DISABLED menu flag, (vol. 1) 4-13, 4-112, 4-186, 
4-258, 4-311, 6-81 
MF_ENABLED menu flag, (vol. 1) 4-13, 4-112, 4-186, 
4-258, 4-311 
MF_END menu option, (vol. 2) 7-51 
MF_GRAYED menu flag, (vol. 1) 4-13, 4-112, 4-186, 
4-258, 4-311, 6-81 
MF_HELP menv-item option, (vol. 2) 7-51 
MF_HILITE menu flag, (vol. 1) 4-253 
MF_MENUBARBREAK menu flag, (vol. 1) 4-13, 
4-186, 4-258, 4-311 
MF_MENUBARBREAK menu-item option, (vol. 2) 7-51 
MF_MENUBREAK menu flag, (vol. 1) 4-13, 4-186, 
4-258, 4-312 
MF_MENUBREAK menv-item option, (vol. 2) 7-51 
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MF_MOUSESELECT menu flag, (vol. 1) 6-81 
MF_OWNERDRAW menu flag, (vol. 1) 4-13, 4-259, 
4-312, 6-81 
MF_OWNERDRAW menu-item option, (vol. 2) 7-51 
MF_POPUP menu flag, (vol. 1) 4-14, 4-259, 4-312, 6-81 
MF_POPUP menu-item option, (vol. 2) 7-51 
MF_SEPARATOR menu flag, (vol. 1) 4-14, 4-186, 
4-259, 4-312 
MF_STRING menu flag, (vol. 1) 4-14, 4-259, 4-312 
MF_SYSMENU menu flag, (vol. 1) 6-81 
MF_UNCHECKED menu flag, (vol. 1) 4-14, 4-25, 
4-186, 4-259, 4-312 
MF_UNHILITE menu flag, (vol. 1) 4-253 
MFCOMMENT printer escape, (vol. 2) 12-38 
MIDCREATESTRUCT menu flag, (vol. 2) 7-48 
min macro, (vol. 1) 4-309 
Minimize box, (vol. 2) 8-17 
Minus (-) sign, (vol. 2) 14-7 
MK_CONTROL mouse-key code, (vol. 1) 6-71 to 6-74, 
6-82, 6-96 to 6-97 
MK_LBUTTON mouse-key code, (vol. 1) 6-71, 6-73 to 
6-74, 6-82, 6-96 to 6-97 
MK_MBUTTON mouse-key code, (vol. 1) 6-71 to 6-73, 
6-82, 6-96 to 6-97 
MK_RBUTTON mouse-key code, (vol. 1) 6-71 to 6-74, 
6-82, 6-96 
MK_SHIFT mouse-key code, (vol. 1) 6-71 to 6-74, 6-82, 
6-96 to 6-97 
MM_ANISOTROPIC mapping mode, (vol. 1) 4-383 
MM_HIENGLISH mapping mode, (vol. 1) 4-383 
MM_HIMETRIC mapping mode, (vol. 1) 4-383 
MM_ISOTROPIC mapping mode, (vol. 1) 4-384 
MM_LOENGLISH mapping mode, (vol. 1) 2-20, 4-384 
MM_LOMETRIC mapping mode, (vol. 1) 4-384 
MM_TEXT mapping mode, (vol. 1) 2-19, 4-384 
MM_TWIPS mapping mode, (vol. 1) 4-384 
Mnemonic, (vol. 2) 8-10, 8-21 to 8-25, 8-27 to 8-29 
ModifyMenu function, (vol. 1) 1-57, 4-211, 4-309 to 
4-311, 6-106 
Module-definition file 

CODE statement, (vol. 2) 10-2 

DATA statement, (vol. 2) 10-2 

DESCRIPTION statement, (vol. 2) 10-3 

EXETYPE statement, (vol. 2) 10-4 

EXPORTS statement, (vol. 2) 10-4 

HEAPSIZE statement, (vol. 2) 10-5 

IMPORTS statement, (vol. 2) 10-6 

LIBRARY statement, (vol. 2) 10-7 

module statement, (vol. 2) 10-1 

NAME statement, (vol. 2) 10-7 

SEGMENTS statement, (vol. 2) 10-8 

STACKSIZE statement, (vol. 2) 10-9 

STUB statement, (vol. 2) 10-10 


Module statement in module-definition file, (vol. 2) 10-1 
Mouse cursor. See Cursor 
MOVEABLE resource-compiler key word, (vol. 2) 8-2, 
8-4 to 8-6, 8-9, 8-14 
MoveTo function, (vol. 1) 2-22, 4-312 
MoveWindow function, (vol. 1) 1-29, 4-313 
MSG data structure, (vol. 2) 7-53 
MSGF_DIALOGBOxX filter-function message type, (vol. 
1) 4-426 to 4-427 
MSGF_MENU filter-function message type, (vol. 1) 
4-426 to 4-427 
MSGF_MESSAGEBOxX filter-function message type, 
(vol. 1) 4-427 
MulDiv function, (vol. 1) 3-13, 4-314 
MULTIKEYHELP data structure, (vol. 2) 7-53 
Multiple document interface (MDI) 
child window, (vol. 2) 7-16 
activating, (vol. 1) 6-75, 6-78 
active, (vol. 1) 6-77 
cascading, (vol. 1) 6-75 
closing, (vol. 1) 6-76 
creating, (vol. 1) 6-75, (vol. 2) 7-47 
default function, (vol. 1) 4-84 
maximizing, (vol. 1) 6-77 
restoring, (vol. 1) 6-78 
. system accelerator, (vol. 1) 4-445 
tiling, (vol. 1) 6-79 
client window, (vol. 1) 6-75 to 6-77, 6-79 
described, (vol. 1) 1-25 
frame window default function, (vol. 1) 4-81 
messages, (vol. 1) 5-19 
system accelerator, (vol. 1) 4-445 
Multiple-line edit control, (vol. 2) 8-40 
Multiple-line resource statement 
ACCELERATORS, (vol. 2) 8-7 
DIALOG, (vol. 2) 8-13 
MENU, (vol. 2) 8-8 
RCDATA, (vol. 2) 8-4 
STRINGTABLE, (vol. 2) 8-5 
Multitasking, defined, (vol. 1) xvi 


N 


NAME module-definition statement, (vol. 2) 10-7 
NAME statement, (vol. 2) 10-1 
Naming 

conventions, data types, (vol. 2) 7-5 

executable module, (vol. 2) 10-7 

imported functions, (vol. 2) 10-6 

library module, (vol. 2) 10-7 
NEAR data type, (vol. 2) 7-4 
NETBIOS interrupt, function request (SCH), (vol. 1) 
4-315 
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NetBIOSCall function, (vol. 1) 3-6, 4-315 
NEWFRAME printer escape, (vol. 2) 12-38 
NEXTBAND printer escape, (vol. 2) 12-39 
NOINVERT option, ACCELERATORS resource 
statement, (vol. 2) 8-8 
Non-resident segments, (vol. 2) 14-5 
NOPARITY parity type, (vol. 2) 7-23 
Notification codes 

button, (vol. 1) 5-15 

edit control, (vol. 1) 5-16 
NPSTR data type, (vol. 2) 7-4 
NULL_BRUSH stock object, (vol. 1) 4-207 
NULL_PEN stock object, (vol. 1) 4-207 
NULLREGION region type, (vol. 1) 4-32, 4-129 to 
4-130, 4-158, 4-224, 4-260, 4-318 to 4-319, 4-359 
NUMBRUSHES device capability, (vol. 1) 4-167 
NUMCOLORS device capability, (vol. 1) 4-167 
NUMFONTS device capability, (vol. 1) 4-167 
NUMPENS device capability, (vol. 1) 4-167 


0 


ODA_DRAWENTIRE drawing action, (vol. 2) 7-37 
ODA_FOCUS drawing action, (vol. 2) 7-37 
ODA_SELECT drawing action, (vol. 2) 7-37 
ODDPARITY parity type, (vol. 2) 7-23 
ODS_CHECKED owner-draw control status, (vol. 2) 
7-37 
ODS_DISABLED owner-draw control status, (vol. 2) 
7-37 
ODS_FOCUS owner-draw control status, (vol. 2) 7-37 
ODS_GRAYED owner-draw control status, (vol. 2) 7-37 
ODS_SELECTED owner-draw control status, (vol. 2) 
7-37 ; 
ODT_BUTTON owner-draw control type, (vol. 2) 7-36, 
7-49 
ODT_COMBOBOxX owner-draw control type, (vol. 2) 
7-19, 7-27, 7-36, 7-49 

- ODT_LISTBOX owner-draw control type, (vol. 2) 7-19, 
7-27, 7-36, 7-49 
ODT_MENU owner-draw control type, (vol. 2) 7-36, 
7-49 
OEM_FIXED_FONT stock object, (vol. 1) 4-207 
OemKeyScan function, (vol. 1) 1-31, 4-316 
OemToAnsi function, (vol. 1) 3-9, 4-316 
OemToAnsiBuff function, (vol. 1) 3-9, 4-317 
OF_CANCEL option, (vol. 1) 4-323 
OF_CREATE option, (vol. 1) 4-323 
OF_DELETE option, (vol. 1) 4-323 
OF_EXIST option, (vol. 1) 4-323 
OF_PARSE option, (vol. 1) 4-323 
OF_PROMPT option, (vol. 1) 4-323 
OF_READ option, (vol. 1) 4-295, 4-323 


OF_READWRITE option, (vol. 1) 4-295 
OF_REOPEN option, (vol. 1) 4-323 
OF_VERIFY option, (vol. 1) 4-325 
OF_WRITE option, (vol. 1) 4-296, 4-325 
OFFSET macro, Cmacro, (vol. 2) 14-6 
Offset value, (vol. 2) 14-4, 14-6 
OffsetClipRgn function, (vol. 1) 2-22, 4-317 
OffsetRect function, (vol. 1) 1-67 to 1-68, 4-318 
OffsetRgn function, (vol. 1) 2-21, 4-319 
OffsetViewportOrg function, (vol. 1) 2-15, 4-319 
OffsetWindowOrg function, (vol. 1) 2-15, 4-320 
OFSTRUCT data structure, (vol. 2) 7-54 
ONESSTOPBITS stop-bits type, (vol. 2) 7-24 
ONESTOPBIT stop-bits type, (vol. 2) 7-24 
OPAQUE background mode, (vol. 1) 4-365 
OpenClipboard function, (vol. 1) 1-59, 4-321 
OpenComm function, (vol. 1) 3-11, 4-321 
OpenFile function, (vol. 1) 3-14, 4-322 to 4-324 
OpenIcon function, (vol. 1) 1-29, 4-325 
OpenSound function, (vol. 1) 3-12, 4-326 
Option 

MENUBARBREAK, (vol. 2) 8-11 

MENUBREAK, (vol. 2) 8-11 

SHIFT, (vol. 2) 8-8 
Option, Cmacro 

memC, (vol. 2) 13-2 

memL, (vol. 2) 13-2 

memM, (vol. 2) 13-2 

memory-model, (vol. 2) 13-2 

memS, (vol. 2) 13-2 

?PLM, (vol. 2) 13-3 

stack-checking, (vol. 2) 13-6 

IWIN, (vol. 2) 13-4 
Option, menu-item 

CHECKED, (vol. 2) 8-10, 8-12 

GRAYED, (vol. 2) 8-11 to 8-12 

HELP, (vol: 2) 8-10 

INACTIVE, (vol. 2) 8-10 to 8-11 

MENUBARBREAK, (vol. 2) 8-12 
OR operator, (vol. 2) 8-12, 8-21 to 8-22, 8-24 to 8-27, 
8-30 to 8-32 
Origin 

brush, default, (vol. 1) 1-33 

viewport, default, (vol. 1) 1-33 

window, default, (vol. 1) 1-34 
OutputDebugString function, (vol. 1) 3-14, 4-326 
Overlapped window, (vol. 1) 1-22 
Overriding types, (vol. 2) 13-9 
Owner-draw button. See Button, owner-draw 
Owner-draw control. See Control, owner-draw 
Owner-draw dialog box controls, (vol. 1) 1-51 
Owner-draw menu. See Menu, owner-draw 
OWNERDRAWFIXED resource option, (vol. 1) 6-80 
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P 


PAGE alignment type, (vol. 2) 14-5 
Painting 
functions, (vol. 1) 1-31 
inverting, drawing, filling, (vol. 1) 1-39 
rectangles, (vol. 1) 1-39 
systems display, (vol. 1) 1-31 
updating 
background, (vol. |) 1-38 
displays, (vol. 1) 1-37 
nonclient area, (vol. 1) 1-42 
validating 
rectangle, (vol. 1) 4-455 
region, (vol. 1) 4-455 
PaintRgn function, (vol. 1) 2-21, 4-327 
PAINTSTRUCT data structure, (vol. 2) 7-55 
Palette, logical. See Logical palette 
Palette, system, retrieving entries, (vol. 1) 4-213 
PALETTEENTRY data structure, (vol. 2) 7-45, 7-55 
PALETTEINDEX utility macro, (vol. 1) 3-13, 4-327 
PALETTERGB utility macro, (vol. 1) 3-13, 4-327 
PARA alignment type, (vol. 2) 14-5 
Parentheses ( ) 
as document convention, (vol. 1) xxiv 
overriding type, (vol. 2) 13-10 
parmX macro, Cmacro, (vol. 2) 13-9 to 13-10, 14-5 
Pascal calling convention, (vol. 2) 13-3 to 13-4 
PASSTHROUGH printer escape, (vol. 2) 12-40 
PatBlt function, (vol. 1) 2-26, 4-328 
PATCOPY raster operation, (vol. 1) 4-19 
PATINVERT raster operation, (vol. 1) 4-19 
PATPAINT raster operation, (vol. 1) 4-19 
PC_EXPLICIT palette-entry option, (vol. 2) 7-56 
PC_NOCOLLAPSE palette-entry option, (vol. 2) 7-56 


PC_RESERVED palette-entry option, (vol. 1) 4-7, (vol. 


2) 7-56 
PDEVICESIZE device capability, (vol. 1) 4-167 
PeekMessage function, (vol. 1) 1-2, 4-329 to 4-330 
Pen : 
creating, (vol. 1) 4-56 to 4-57, (vol. 2) 7-45 
position, default, (vol. 1) 1-33 
Pie function, (vol. 1) 2-24 to 2-25, 4-331 
PINT data type, (vol. 2) 7-4 
PLANES device capability, (vol. 1) 4-167 
PlayMetaFile function, (vol. 1) 2-41, 4-332 
Play MetaFileRecord function, (vol. 1) 2-41, 4-332 
?PLM option 
calling convention, defined, (vol. 2) 13-8 
Cmacro, (vol. 2) 13-3 to 13-4 
Plus (+) operator, (vol. 2) 8-21 to 8-26, 8-28 to 8-33 
Plus (+) sign, with bias value, (vol. 2) 14-7 
PM_NOREMOVE option, (vol. 1) 4-330 


PM_NOYIELD option, (vol. 1) 4-330 
PM_REMOVE option, (vol. 1) 4-330 
POINT data structure, (vol. 1) 4-93, (vol. 2) 7-56 
Pointer naming, Cmacro, (vol. 2) 14-9 
Polygon-filling mode, default, (vol. 1) 1-33 
Polygon function, (vol. 1) 2-24, 4-333 
POLYGONALCAPS device capability, (vol. 1) 4-169 
Polyline function, (vol. 1) 2-22, 4-334 
PolyPolygon function, (vol. 1) 2-24, 4-334 
Pop-up menu 

creating, (vol. 1) 4-59 

described, (vol. 1) 1-26, (vol. 2) 8-11 

nested, (vol. 2) 8-12 
POPUP resource statement, (vol. 2) 8-10 to 8-12 
PostAppMessage function, (vol. 1) 1-2, 4-335 
PostMessage function, (vol. 1) 1-2, 4-335 
PostQuitMessage function, (vol. 1) 1-2, 4-336 
PRELOAD resource-compiler key word, (vol. 2) 8-2 to 
8-4, 8-6, 8-9, 8-13 
Printer-control functions, (vol. 1) 2-44 
Printer device driver 

capabilities, (vol. 1) 4-91 

initialization, (vol. 1) 4-130, (vol. 2) 7-27 
Printer-escape functions 

banding, (vol. 1) 2-45 

creating output, (vol. 1) 2-45 
ProfClear function, (vol. 1) 3-15, 4-337 
ProfFinish function, (vol. 1) 3-15, 4-337 
ProfFlush function, (vol. 1) 3-15, 4-337 
ProfInsChk function, (vol. 1) 3-15, 4-338 
ProfSampRate function, (vol. 1) 3-15, 4-338 
ProfSetup function, (vol. 1) 3-15, 4-338 to 4-339 
ProfStart function, (vol. 1) 3-15, 4-340 
ProfStop function, (vol. 1) 3-15, 4-340 
Programming model, setting, (vol. 2) 13-2 
Prolog 

code, (vol. 2) 13-4 

Windows, (vol. 2) 13-4 
PROOF_QUALITY font quality, (vol. 2) 7-43 
Property list functions, (vol. 1) 1-65 

adding entries, (vol. 1) 1-67 

creating, (vol. 1) 1-67": 

dumping contents, (vol. 1) 1-67 
PSTR data type, (vol. 2) 7-4 
PtInRect function, (vol. 1) 1-67 to 1-68, 4-340 
PtInRegion function, (vol. 1) 2-21, 4-341 
PtVisible function, (vol. 1) 2-22, 4-341 to 4-342 
PUBLIC combine type, Cmacro, (vol. 2) 14-6 
PUBLIC function, Cmacro, (vol. 2) 13-10 
Public labels, (vol. 2) 13-7 
Public variable, (vol. 2) 14-11 
PUSHBUTTON resource statement 

described, (vol. 2) 8-25 
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DIALOG resource statement, (vol. 2) 8-20 
PWORD data type, (vol. 2) 7-4 


Q 


QUERYESCSUPPORT printer escape, (vol. 2) 12-41 


Queue 
application, (vol. 1) 1-3 
checking, (vol. 1) 1-5 
Quotation marks (“”’) 
as document convention, (vol. 1) xxv 
in strings, (vol. 2) 8-7, 8-10 


R 


R2_BLACK raster drawing mode, (vol. 2) 11-2 to 11-3 


R2_COPYPEN raster drawing mode, (vol. 2) 11-2 to 11-3 
R2_MASKNOTPEN raster drawing mode, (vol. 1) 
4-395, (vol. 2) 11-2 to 11-3 
R2_MASKPEN raster drawing mode, (vol. 1) 4-395, 
(vol. 2) 11-2 to 11-4 
R2_MASKPENNOT raster drawing mode, (vol. 1) 
4-395, (vol. 2) 11-2 to 11-4 
R2_MERGENOTPEN raster drawing mode, (vol. 1) 
4-395, (vol. 2) 11-2 to 11-4 
R2_MERGEPEN raster drawing mode, (vol. 1) 4-395, 
(vol. 2) 11-2 to 11-4 
R2_MERGEPENNOT raster drawing mode, (vol. 1) 
4-395, (vol. 2) 11-2 to 11-4 
R2_NOP raster drawing mode, (vol. 2) 11-2 to 11-4 
R2_NOT raster drawing mode, (vol. 1) 4-395, (vol. 2) 
11-2 to 11-4 
R2_NOTCOPYPEN raster drawing mode, (vol. 1) 4-395, 
(vol. 2) 11-2 to 11-4 
R2_NOTMASKPEN raster drawing mode, (vol. 1) 
4-395, (vol. 2) 11-2 to 11-4 
R2_NOTMERGEPEN raster drawing mode, (vol. 1) 
4-395, (vol. 2) 11-2 to 11-4 
R2_NOTXORPEN raster drawing mode, (vol. 1) 4-395, 
(vol. 2) 11-2 to 11-4 
R2_WHITE raster drawing mode, (vol. 2) 11-2 to 11-4 
R2_XORPEN raster drawing mode, (vol. 1) 4-395, (vol. 
2) 11-2 to 11-4 
Radio-button control, (vol. 2) 8-29 
RADIOBUTTON resource statement 

described, (vol. 2) 8-29 to 8-30 

DIALOG resource statement, (vol. 2) 8-20 
Raster fonts, digitized aspect, (vol. 1) 2-36 
RASTERCAPS device capability, (vol. 1) 4-168 
Raw-data resource. See RCDATA resource statement 
RC_BANDING device capability, (vol. 1) 4-168 
RC_BITBLT device capability, (vol. 1) 4-168 
RC_BITMAP64 device capability, (vol. 1) 4-168 
RC_DI_BITMAP device capability, (vol. 1) 4-168 


RC diagnostic messages, (vol. 2) B-1 to B-10 
RC_DIBTODEYV device capability, (vol. 1) 4-168 
RC_FLOODFILL device capability, (vol. 1) 4-168 
RC_GDI20_OUTPUT device capability, (vol. 1) 4-168 
RC_PALETTE device capability, (vol. 1) 4-168 
RC_SCALING device capability, (vol. 1) 4-168 
RC_STRETCHBLT device capability, (vol. 1) 4-168 
RC_STRETCHDIB defice capability, (vol. 1) 4-168 
RCDATA resource statement, (vol. 2) 8-4 to 8-5 
ReadComm function, (vol. 1) 3-11, 4-343 
Realize. See Logical palette 
RealizePalette function, (vol. 1) 2-10, 4-343 
RECT data structure, (vol. 2) 7-57 
Rectangle function, (vol. 1) 2-24, 4-344 
Rectangle functions 

additional functions, (vol. 1) 1-67 

coordinates, (vol. 1) 1-67 

in Windows, (vol. 1) 1-67 

InflateRect, (vol. 1) 1-68 

IntersectRect, (vol. 1) 1-68 

IsRectEmpty, (vol. 1) 1-68 

OffsetRect, (vol. 1) 1-68 

PtInRect, (vol. 1) 1-68 

SetRect, (vol. 1) 1-68 

specifying, (vol. 1) 1-67 

UnionRect, (vol. 1) 1-69 
Rectangle, validating, (vol. 1) 4-455 
RectInRegion function, (vol. 1) 2-22, 4-345 
RectVisible function, (vol. 1) 2-22, 4-345 
Region 

rounded rectangle, creating, (vol. 1) 4-60 

validating, (vol. 1) 4-455 
Region functions, (vol. 1) 2-21 
Register 

pointers, (vol. 2) 13-8 

saving, (vol. 2) 14-14 
RegisterClass function, (vol. 1) 1-7, 4-345 
RegisterClipboardFormat function, (vol. 1) 1-59, 4-346 
RegisterWindowMessage function, (vol. 1) 4-347 
Relative-absolute flag, default setting, (vol. 1) 1-33 
ReleaseCapture function, (vol. 1) 1-30, 4-348 
ReleaseDC function, (vol. 1) 1-32, 4-348 
RemoveFontResource function, (vol. 1) 2-28, 4-348 
RemoveMenu function, (vol. 1) 1-57, 4-349 
RemoveProp function, (vol. 1) 1-65, 4-350 
ReplyMessage function, (vol. 1) 1-2, 4-351 
Reserved messages, (vol. 1) 6-1 
RESETDEV communication function code, (vol. 1) 4-128 
Resource 

bitmap, (vol. 2) 8-2 

cursor, (vol. 2) 8-2 

font, (vol. 2) 8-2 

icon, (vol. 2) 8-2 
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loading, (vol. 2) 8-2 to 8-4, 8-6, 8-13 

managing hooks, (vol. 1) 1-63 

raw data, (vol. 2) 8-4 

string, (vol. 2) 8-5 

user-defined, (vol. 2) 8-3 

Resource directive 

#define, (vol. 2) 8-48 

described, (vol. 2) 8-47 

#elif, (vol. 2) 8-50 

#else, (vol. 2) 8-50 

#endif, (vol. 2) 8-51 

#if, (vol. 2) 8-49 

#ifdef, (vol. 2) 8-48 

#ifndef, (vol. 2) 8-49 

#include, (vol. 2) 8-47 

#undef, (vol. 2) 8-48 

Resource statement 
ACCELERATORS 
. CONTROL option, (vol. 2) 8-8 

NOINVERT option, (vol. 2) 8-8 
SHIFT option, (vol. 2) 8-8 

DIALOG 
CAPTION statement, (vol. 2) 8-18 
CHECKBOX statement, (vol. 2) 8-23 
CLASS statement, (vol. 2) 8-19 
COMBOBOX statement, (vol. 2) 8-31 
CONTROL statement, (vol. 2) 8-34 
CTEXT statement, (vol. 2) 8-22 


DEFPUSHBUTTON statement, (vol. 2) 8-28 


described, (vol. 2) 8-13 
dialog control statements, (vol. 2) 8-20 
dialog option statements, (vol. 2) 8-15 
EDITTEXT statement, (vol. 2) 8-30 
FONT statement, (vol. 2) 8-19 
GROUPBOXxX statement, (vol. 2) 8-27 
ICON statement, (vol. 2) 8-33 
LISTBOX statement, (vol. 2) 8-26 
LTEXT statement, (vol. 2) 8-20 
MENU statement, (vol. 2) 8-18 
options, (vol. 2) 8-13 
PUSHBUTTON statement, (vol. 2) 8-25 
RADIOBUTTON statement, (vol. 2) 8-29 
RTEXT statement, (vol. 2) 8-21 
SCROLLBAR statement, (vol. 2) 8-33 
STYLE statement, (vol. 2) 8-15 
MENU, (vol. 2) 8-8 to 8-11, 8-13 
RCDATA, (vol. 2) 8-4 to 8-5 
resource, (vol. 2) 8-1 
single-line, (vol. 2) 8-1 to 8-2 
STRINGTABLE, (vol. 2) 8-5 to 8-6 
user-defined, (vol. 2) 8-3 to 8-4 
RESTORE_CTM printer escape, (vol. 2) 12-41 
RestoreDC function, (vol. 1) 2-2, 4-352 


RGB 

See also Color 

explicit, (vol. 2) 7-17 

palette-relative, (vol. 2) 7-17 
RGB utility macro, (vol. 1) 3-13, 4-352 
RGBQUAD data structure, (vol. 2) 7-11, 7-58 
RGBTRIPLE data structure, (vol. 2) 7-8, 7-58 
RGN_AND region-combining mode, (vol. 1) 4-31 
RGN_COPY region-combining mode, (vol. 1) 4-31 
RGN_DIFF region-combining mode, (vol. 1) 4-31 
RGN_OR region-combining mode, (vol. 1) 4-31 
RGN_XOR region-combining mode, (vol. 1) 4-31 
RoundRect function, (vol. 1) 2-24, 4-353 to 4-354 
RT_ACCELERATOR resource type, (vol. 1) 4-139 
RT_BITMAP resource type, (vol. 1) 4-139 
RT_DIALOG resource type, (vol. .1) 4-139 
RT_FONT resource type 
RT_MENU resource type, (vol. 1) 4-139 
RT_RCDATA resource type, (vol. 1) 4-139 
RTEXT resource statement, (vol. 2) 8-21 to 8-22 


S 


S_ALLTHRESHOLD voice-queue state, (vol. 1) 4-457 
S_LEGATO voice note style, (vol. 1) 4-410 
S_NORMAL voice note style, (vol. 1) 4-410 
S_PERIODS512 voice frequency, (vol. 1) 4-398 
S_PERIOD 1024 voice frequency, (vol. 1) 4-398 
S_PERIOD2048 voice frequency, (vol. 1) 4-398 
S_PERIODVOICE voice frequency, (vol. 1) 4-398 
S_QUEUEEMPTY voice-queue state, (vol. 1) 4-457 
S_SERDCC voice error code, (vol. 1) 4-412 
S_SERDDR voice error code, (vol. 1) 4-414 
S_SERDFQ voice error code, (vol. 1) 4-414 
S_SERDLN voice error code, (vol. 1) 4-412 
S_SERDMD voice error code, (vol. 1) 4-411 
S_SERDNT voice error code, (vol. 1) 4-412 
S_SERDRC voice error code, (vol. 1) 4-412 
S_SERDSH voice error code, (vol. 1) 4-412 
S_SERDTP voice error code, (vol. 1) 4-411 
S_SERDVL voice error code, (vol. 1) 4-411, 4-414 
S_SERMACT voice error code, (vol. 1) 4-413 
S_SEROFM voice error code, (vol. 1) 4-413 
S_SERQFUL voice error code, (vol. 1) 4-411 to 4-412, 
4-414 

S_STACCATO voice note style, (vol. 1) 4-410 
S_THRESHOLD voice-queue state, (vol. 1) 4-457 
S_WHITES12 voice frequency, (vol. 1) 4-398 
S_WHITE1024 voice frequency, (vol. 1) 4-398 
S_WHITE2048 voice frequency, (vol. 1) 4-398 
S_WHITEVOICE voice frequency, (vol. 1) 4-398 
SAVE_CTM printer escape, (vol. 2) 12-42 

Save macro, Cmacro, (vol. 2) 14-14 
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SaveDC function, (vol. 1) 2-2, 4-355 

Saving, registers, (vol. 2) 14-14 

SB_BOTH scroll-bar type, (vol. 1) 4-431 

SB_BOTTOM scrolling request, (vol. 1) 6-65 to 6-66, 
6-112 to 6-113 

SB_CTL scroll-bar type, (vol. 1) 4-205 to 4-206, 4-396 to 
4-397, 4-431 

SB_ENDSCROLL scrolling request, (vol. 1) 6-65 to 
6-66, 6-112 to 6-113 

SB_HORZ scroll-bar type, (vol. 1) 4-205 to 4-206, 4-396 
to 4-397, 4-431 

SB_LINEDOWN scrolling request, (vol. 1) 6-65 to 6-66, 
6-112 to 6-113 

SB_LINEUP scrolling request, (vol. 1) 6-65 to 6-66, 
6-112 to 6-113 

SB_PAGEDOWN scrolling request, (vol. 1) 6-65 to 
6-66, 6-112 to 6-113 

SB_PAGEUP scrolling request, (vol. 1) 6-65 to 6-66, 
6-112 to 6-113 

SB_THUMBPOSITION scrolling request, (vol. 1) 6-65 
to 6-66, 6-112 to 6-113 

SB_THUMBTRACK scrolling request, (vol. 1) 6-65, 
6-112 

SB_TOP scrolling request, (vol. 1) 6-65 to 6-66, 6-112 to 
6-113 

SB_VERT scroll-bar type, (vol. 1) 4-205 to 4-206, 4-396 
to 4-397, 4-431 

sBegin macro, Cmacro, (vol. 2) 14-5, 14-14 
SBS_BOTTOMALIGN control style, (vol. 1) 4-73, (vol. 
2) 8-44 

SBS_HORZ control style, (vol. 1) 4-73, (vol. 2) 8-44 
SBS_LEFTALIGN control style, (vol. 1) 4-73, (vol. 2) 
8-43 

SBS_RIGHTALIGN control style, (vol. 1) 4-73, (vol. 2) 
8-43 

SBS_SIZEBOX control style, (vol. 1) 4-73, (vol. 2) 8-44 
SBS_SIZEBOXBOTTOMRIGHTALIGN control style, 
(vol. 1) 4-73, (vol. 2) 8-44 
SBS_SIZEBOXTOPLEFTALIGN control style, (vol. 1) 
4-74, (vol. 2) 8-44 

SBS_TOPALIGN control style, (vol. 1) 4-74, (vol. 2) 
8-44 

SBS_VERT control style, (vol. 1) 4-74, (vol. 2) 8-43 
SC_CLOSE system command, (vol. 1) 6-105 
SC_HSCROLL system command, (vol. 1) 6-105 
SC_KEYMENU system command, (vol. 1) 6-105 
SC_MAXIMIZE system command, (vol. 1) 6-105 
SC_MINIMIZE system command, (vol. 1) 6-105 
SC_MOUSEMENU system command, (vol. 1) 6-105 
SC_MOVE system command, (vol. 1) 6-106 
SC_NEXTWINDOW system command, (vol. 1) 6-106 
SC_PREVWINDOW system command, (vol. 1) 6-106 
SC_RESTORE system command, (vol. 1) 6-106 


SC_SIZE system command, (vol. 1) 6-106 


SC_VSCROLL system command, (vol. 1) 6-106 


ScaleViewportExt function, (vol. 1) 2-15, 4-355 
ScaleWindowExt function, (vol. 1) 2-15, 4-356 
ScreenToClient function, (vol. 1) 2-20, 4-356 
Scroll bar 
control-class styles, (vol. 2) 8-41, 8-43 
described, (vol. 1) 1-25 
horizontal, (vol. 2) 8-17 
vertical, (vol. 2) 8-18 
SCROLLBAR control class 
control styles, (vol. 2) 8-43 
described, (vol. 1) 4-65, (vol. 2) 8-36 
SCROLLBAR resource statement, (vol. 2) 8-33 
ScrollDC function, (vol. 1) 1-53, 4-357 
Scrolling 
described, (vol. 1) 1-55 
functions 
controlling, (vol. 1) 1-54 
described, (vol. 1) 1-53 
processing, (vol. 1) 1-55 
requests, (vol. 1) 1-55 
hiding, (vol. 1) 1-56 
using thumb, (vol. 1) 1-54 
ScrollWindow function, (vol. 1) 1-53, 4-358 
Segment 
alignment type, (vol. 2) 14-6 
class name, (vol. 2) 14-6 
combine type, (vol. 2) 14-6 
Segment macros, Cmacro, (vol. 2) 13-6 
Segment types, mixed, (vol. 2) E-5 to E-6 
Segmented memory mode, (vol. 2) E-2 
SEGMENTS module-definition statement, (vol. 2) 10-8 
SEGMENTS statement, (vol. 2) 10-1 
segNameOFFSET macro, Cmacro, (vol. 2) 14-14 
SelectClipRgn function, (vol. 1) 2-22, 4-359 
SelectObject function, (vol. 1) 2-6, 4-360 
SelectPalette function, (vol. 1) 2-10, 4-361 
SELECTPAPERSOURCE printer escape. See 
GETSETPAPERBINS printer escape 
sEnd macro, Cmacro, (vol. 2) 14-5, 14-15 
SendDlgItemMessage function, (vol. 1) 1-44, 4-362 
SendMessage function 
described, (vol. 1) 1-2 to 1-3, 4-362 
message deadlock caused by, (vol. 1) 1-6 
SET_ARC_DIRECTION printer escape, (vol. 2) 12-45 
SET_BACKGROUND_COLOR printer escape, (vol. 2) 
12-46 
SET_BOUNDS printer escape, (vol. 2) 12-47 
SET_POLY_MODE printer escape, (vol. 2) 12-53 to 
12-54 
SET_SCREEN_ANGLE printer escape, (vol. 2) 12-55 
SET_SPREAD printer escape, (vol. 2) 12-56 
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SETABORTPROC printer escape, (vol. 2) 12-43 
SetActiveWindow function, (vol. 1) 1-30, 4-363 
SETALLJUSTVALUES printer escape, (vol. 2) 12-44 
SetBitmapBits function, (vol. 1) 2-26, 4-363 
SetBitmapDimension function, (vol. 1) 2-26, 4-364 
SetBkColor function, (vol. 1) 2-14, 4-364 

SetBkMode function, (vol. 1) 2-14, 4-365 
SetBrushOrg function, (vol. 1) 2-6, 4-365 

SetCapture function, (vol. 1) 1-30, 4-366 
SetCaretBlinkTime function, (vol. 1) 1-60, 4-366 
SetCaretPos function, (vol. 1) 1-60, 4-367 
SetClassLong function, (vol. 1) 1-8, 1-16, 4-367 
SetClassWord function, (vol. 1) 1-8, 4-368 
SetClipboardData function, (vol. 1) 1-59, 4-369 to 4-371 
SetClipboardViewer function, (vol. 1) 1-59, 4-372 
SETCOLORTABLE printer escape, (vol. 2) 12-48 
SetCommBreak function, (vol. 1) 3-11, 4-372 
SetCommEventMask function, (vol. 1) 3-11, 4-373 
SetCommState function, (vol. 1) 3-11, 4-374 
SETCOPYCOUNT printer escape, (vol. 2) 12-49 
SetCursor function, (vol. 1) 1-62, 4-374 

SetCursorPos function, (vol. 1) 1-62, 4-375 

SetDIBits function, (vol. 1) 2-13, 2-26, 4-168, 4-375 to 
4-376 

SetDIBitsToDevice function, (vol. 1) 2-26, 4-168, 4-377 
to 4-378 

SetDlgItemInt function, (vol. 1) 1-44, 4-378 
SetDlgItemText function, (vol. 1) 1-44, 4-379 
SetDoubleClickTime function, (vol. 1) 1-30, 4-379 
SETDTR communication function code, (vol. 1) 4-128 
SETENDCAP printer escape. See SETLINECAP printer 
escape 

SetEnvironment function, (vol. 1) 2-47, 4-380 
SetErrorMode function, (vol. 1) 3-7, 4-380 

SetFocus function, (vol. 1) 1-30, 4-381 
SetHandleCount function, (vol. 1) 3-14, 4-382 
SETKERNTRACK printer escape, (vol. 2) 12-50 
SetKeyboardState function, (vol. 1) 1-31, 4-382 
SETLINECAP printer escape, (vol. 2) 12-51 
SETLINEJOIN printer escape, (vol. 2) 12-52 
SetMapMode function, (vol. 1) 2-15, 4-383 
SetMapperFlags function, (vol. 1) 2-28, 2-36, 4-384 
SetMenu function, (vol. 1) 1-57, 4-385 
SetMenultemBitmaps function, (vol. 1) 1-57, 4-14, 
4-184, 4-385 

SetMessageQueue function, (vol. 1) 1-2, 4-386 
SetMetaFileBits function, (vol. 1) 2-41, 4-387 
SETMITERLIMIT printer escape, (vol. 2) 12-53 
SetPaletteEntries function, (vol. 1) 2-10, 4-387 
SetParent function, (vol. 1) 1-58, 4-388 

SetPixel function, (vol. 1) 2-26, 4-388 
SetPolyFillMode function, (vol. 1) 2-14, 4-333 to 4-334, 
4-389 


SetProp function, (vol. 1) 1-65, 4-390 

SetRect function, (vol. 1) 1-68, 4-390 

SetRectEmpty function, (vol. 1) 1-67, 4-391 
SetRectRgn function, (vol. 1) 2-22, 4-391 
SetResourceHandler function, (vol. 1) 3-8, 4-392 to 4-393 
SetROP2 function, (vol. 1) 2-14, 4-394 to 4-395 
SETRTS communication function code, (vol. 1) 4-128 
SetScrollPos function, (vol. 1) 1-53, 4-396 
SetScrollRange function, (vol. 1) 1-53, 4-397 
SetSoundNoise function, (vol. 1) 3-12, 4-398 
SetStretchBltMode function, (vol. 1) 2-14, 4-398 
SetSwapAreaSize function, (vol. 1) 3-4, 4-399 
SetSysColors function, (vol. 1) 1-58, 4-400 
SetSysModal Window function, (vol. 1) 1-30, 4-401 
SetSystemPaletteUse function, (vol. 1) 2-10, 4-214, 4-402 
SetTextAlign function, (vol. 1) 2-27, 4-403 to 4-404 
SetTextCharacterExtra function, (vol. 1) 4-405 
SetTextColor function, (vol. 1) 2-14, 4-250, 4-405 
SetTextJustification function, (vol. 1) 2-27, 4-406 
SetTimer function, (vol. 1) 1-30, 4-407 
SetViewportExt function, (vol. 1) 2-15, 4-408 
SetViewportOrg function, (vol. 1) 2-15, 4-409 
SetVoiceAccent function, (vol. 1) 3-12, 4-410 
SetVoiceEnvelope function, (vol. 1) 3-12, 4-411 
SetVoiceNote function, (vol. 1) 3-12, 4-412 

Set VoiceQueueSize function, (vol. 1) 3-12, 4-413 
SetVoiceSound function, (vol. 1) 3-12, 4-413 
SetVoiceThreshold function, (vol. 1) 3-12, 4-414 
SetWindowExt function, (vol. 1) 2-15, 4-414 
SetWindowLong function, (vol. 1) 1-8, 1-16, 4-415 
SetWindowOrg function, (vol. 1) 2-15, 4-416 
SetWindowPos function, (vol. 1) 1-29, 4-417 to 4-418 
SetWindowsHook function, (vol. 1) 1-64, 4-419 to 4-426 
SetWindowText function, (vol. 1) 1-25, 1-29, 4-427 
SetWindowWord function, (vol. 1) 1-8, 4-428 
SETXOFF communication function code, (vol. 1) 4-128 
SETXON communication function code, (vol. 1) 4-128 
SHIFT option, ACCELERATORS resource statement, 
(vol. 2) 8-8 

short data type, (vol. 2) 7-4 

ShowCaret function, (vol. 1) 1-60, 4-429 

ShowCursor function, (vol. 1) 1-62, 4-429 
ShowOwnedPopups function, (vol. 1) 1-29, 4-430 
ShowScrollBar function, (vol. 1) 1-53, 4-430 
ShowWindow function, (vol. 1) 1-29, 4-282, 4-431, 4-459 
SIMPLEREGION region type, (vol. 1) 4-32, 4-129 to 
4-130, 4-158, 4-224, 4-260, 4-318 to 4-319, 4-359 
Single-line resource statement, (vol. 2) 8-1 to 8-2 
Size-box control, (vol. 2) 8-17, 8-36 
SIZEFULLSCREEN window-sizing request, (vol. 1) 
6-102 

SIZEICONIC window-sizing request, (vol. 1) 6-102 
SIZENORMAL window-sizing request, (vol. 1) 6-102 
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SizeofResource function, (vol. 1) 3-8, 4-432 
SIZEZOOMHIDE window-sizing request, (vol. 1) 6-102 
SIZEZOOMSHOW window-sizing request, (vol. 1) 6-102 
SM_CXBORDER system-metric value, (vol. 1) 4-212 
SM_CXDLGFRAME system-metric value, (vol. 1) 4-212 
SM_CXFRAME system-metric value, (vol. 1) 4-212 
SM_CXFULLSCREEN system-metric value, (vol. 1) 
4-213 

SM_CXHSCROLL system-metric value, (vol. 1) 4-212 
SM_CXHTHUMB system-metric value, (vol. 1) 4-212 
SM_CXMINTRACK system-metric value, (vol. 1) 4-213 
SM_CXSIZE system-metric value, (vol. 1) 4-213 
SM_CXVSCROLL system-metric value, (vol. 1) 4-212 
SM_CYBORDER system-metric value, (vol. 1) 4-212 
SM_CYDLGFRAME system-metric value, (vol. 1) 4-212 
SM_CYFRAME system-metric value, (vol. 1) 4-212 
SM_CYFULLSCREEN system-metric value, (vol. 1) 
4-213 

SM_CYHSCROLL system-metric value, (vol. 1) 4-212 
SM_CYSIZE system-metric value, (vol. 1) 4-213 
SM_CYVSCROLL system-metric value, (vol. 1) 4-212 
SM_CYVTHUMB system-metric value, (vol. 1) 4-212 
SM_DEBUG system-metric value, (vol. 1) 4-213 
SM_MOUSEPRESENT system-metric value, (vol. 1) 
4-213 

SM_SWAPBUTTON system-metric value, (vol. 1) 4-213 
Small capital letters, as document convention, (vol. 1) 
xxv, (vol. 2) x 

SP_APPABORT escape error code, (vol. 2) 12-38 to 
12-39 

SP_ERROR escape error code, (vol. 1) 4-127, (vol. 2) 
12-38 to 12-39 

SP_OUTOFDISK escape error code, (vol. 1) 4-127, (vol. 
2) 12-39 to 12-40 

SP_OUTOFMEMORY escape error code, (vol. 1) 4-127, 
(vol. 2) 12-39 to 12-40 

SP_USERABORT escape error code, (vol. 1) 4-127, 
(vol. 2) 12-39 to 12-40 

SPACEPARITY parity type, (vol. 2) 7-24 
Special-definition macros, Cmacro, (vol. 2) 13-8 
SRCAND raster operation, (vol. 1) 4-19 

SRCCOPY raster operation, (vol. 1) 4-19 

SRCERASE raster operation, (vol. 1) 4-19 

SRCINVERT raster operation, (vol. 1) 4-19 

SRCPAINT raster operation, (vol. 1) 4-19 
SS_BLACKFRAME control style, (vol. 1) 4-74, (vol. 2) 
8-46 

SS_BLACKRECT control style, (vol. 1) 4-74, (vol. 2) 
8-46 

SS_CENTER control style, (vol. 1) 4-74, (vol. 2) 8-45 
SS_GRAYFRAME control style, (vol. 1) 4-74, (vol. 2) 
8-47 


SS_GRAYRECT control style, (vol. 1) 4-74, (vol. 2) 8-46 © 


SS_ICON control style, (vol. 1) 4-74, (vol. 2) 8-33, 8-46 
SS_LEFT control style, (vol. 1) 4-75, (vol. 2) 8-45 
SS_LEFTNOWORDWRAP control style, (vol. 1) 4-75, 
(vol. 2) 8-45 
SS_NOPREFIX control style, (vol. 1) 4-75, (vol. 2) 8-46 
SS_RIGHT control style, (vol. 1) 4-75, (vol. 2) 8-45 
SS_SIMPLE control style, (vol. 1) 4-75, (vol. 2) 8-45 
SS_USERITEM control style, (vol. 1) 4-75, (vol. 2) 8-47 
SS_WHITEFRAME control style, (vol. 1) 4-75, (vol. 2) 
8-47 
SS_WHITERECT control style, (vol. 1) 4-75, (vol. 2) 
8-46 
Stack 
local, (vol. 2) 10-9 
mixed segment types, (vol. 2) E-5 to E-6 
Stack-checking option, Cmacro, (vol. 2) 13-6 
STACK combine type, Cmacro, (vol. 2) 14-6 
STACKSIZE module-definition statement, (vol. 2) 10-1, 
10-9 
Standard C calling convention, (vol. 2) 13-3 
STARTDOC printer escape, (vol. 2) 12-57 
StartSound function, (vol. 1) 3-12, 4-433 
Statement 
See also specific statement 
module-definition file 
EXETYPE, (vol. 2) 10-4 
LIBRARY, (vol. 2) 10-7 
NAME, (vol. 2) 10-7 
STATIC control class, (vol. 1) 4-65, (vol. 2) 8-36 
Static-memory storage 
macros, (vol. 2) 13-7 
private, (vol. 2) 14-15 
public, (vol. 2) 14-10 
staticX macro, Cmacro, (vol. 2) 14-15 
StopSound function, (vol. 1) 3-12, 4-433 
Storage 
static-memory, private, (vol. 2) 14-15 
static-memory, public, (vol. 2) 14-10 
Storage-allocation macros, Cmacro, (vol. 2) 13-7 
Storage size, (vol. 2) 14-9 to 14-13, 14-15 
StretchBlt function 
and color palettes, (vol. 1) 2-13 
described, (vol. 1) 2-26, 4-433 to 4-434 
StretchDIBits function, (vol. 1) 2-27, 4-435 to 4-436 
Stretching mode, default, (vol. 1) 1-33 
String messages, (vol. 1) 6-1 
String resource 


See also RCDATA resource statement; STRINGTABLE 


resource statement 
described, (vol. 2) 8-5 

Strings 
comparing, (vol. 1) 4-298 to 4-299 
concatenating, (vol. 1) 4-297 
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8-31 
WS_THICKFRAME, (vol. 2) 8-18 
WS_VISIBLE, (vol. 2) 8-18 
WS_VSCROLL, (vol. 2) 8-18, 8-26, 8-31 
Styles 
dialog box controls, (vol. 1) 1-48 


copying, (vol. 1) 4-299 

determining length of, (vol. 1) 4-300 

formatting, (vol. 1) 4-465, 4-467 
STRINGTABLE resource statement, (vol. 2) 8-5 to 8-6 
STUB module-definition statement, (vol. 2) 10-1, 10-10 
Style, control 


BUTTON class, (vol. 2) 8-24 to 8-25, 8-27, 8-29 to 8-30 

COMBOBOxX class, (vol. 2) 8-32 

default 
CHECKBOX statement, (vol. 2) 8-24 
COMBOBOxX statement, (vol. 2) 8-32 
CTEXT statement, (vol. 2) 8-23 
DEFPUSHBUTTON statement, (vol. 2) 8-29 
EDITTEXT statement, (vol. 2) 8-31 
GROUPBOxX statement, (vol. 2) 8-28 
ICON statement, (vol. 2) 8-33 
LISTBOX< statement, (vol. 2) 8-26 
LTEXT statement, (vol. 2) 8-21 
PUSHBUTTON statement, (vol. 2) 8-25 
RADIOBUTTON statement, (vol. 2) 8-30 
RTEXT statement, (vol. 2) 8-22 

DS_ABSALIGN, (vol. 2) 8-14 to 8-15 

EDIT class, (vol. 2) 8-31 

LISTBOX< class, (vol. 2) 8-26 

STATIC class, (vol. 2) 8-33 


STYLE resource statement 


DIALOG resource statement, (vol. 2) 8-14 to 8-15 
listing window style, (vol. 2) 8-15 
when #include directive required with, (vol. 2) 8-15 


Style, window 


listing, (vol. 2) 8-15 

WS_BORDER, (vol. 2) 8-16, 8-26 

WS_CAPTION, (vol. 2) 8-16 

WS_CHILD, (vol. 2) 8-14, 8-16 
WS_CHILDWINDOW, (vol. 2) 8-16 
WS_CLIPCHILDREN, (vol. 2) 8-16 
WS_CLIPSIBLINGS, (vol. 2) 8-16 

WS_DISABLED, (vol. 2) 8-16, 8-25, 8-27, 8-29 to 8-31 
WS_DLGFRAME, (vol. 2) 8-16 

WS_GROUP, (vol. 2) 8-17, 8-21 to 8-25, 8-29 to 8-31 
WS_HSCROLL, (vol. 2) 8-17, 8-31 

WS_ICONIC, (vol. 2) 8-17 

WS_MAXIMIZE, (vol. 2) 8-17 
WS_MAXIMIZEBOX, (vol. 2) 8-17 
WS_MINIMIZE, (vol. 2) 8-17 

WS_MINIMIZEBOX, (vol. 2) 8-17 
WS_OVERLAPPED, (vol. 2) 8-17 
WS_OVERLAPPEDWINDOW, (vol. 2) 8-17 
WS_POPUP, (vol. 2) 8-17 

WS_POPUPWINDOW, (vol. 2) 8-17 
WS_SIZEBOX, (vol. 2) 8-17 

WS_SYSMENU, (vol. 2) 8-17 

WS_TABSTOP, (vol. 2) 8-17, 8-21 to 8-25, 8-27, 8-29 to 


formatted text, (vol. 1) 1-41 
Subclassing windows, (vol. 1) 1-16, 4-368, 4-416 
SW_HIDE window state, (vol. 1) 4-432 
SW_MINIMIZE window state, (vol. 1) 4-432 
SW_PARENTCLOSING window state, (vol. 1) 6-101 
SW_PARENTOPENING window state, (vol. 1) 6-101 
SW_RESTORE window state, (vol. 1) 4-432 
SW_SHOW window state, (vol. 1) 4-432 
SW_SHOWMAXIMIZED window state, (vol. 1) 4-432 
SW_SHOWMINIMIZED window state, (vol. 1) 4-432 
SW_SHOWMINNOACTIVE window state, (vol. 1) 
4-432 
SW_SHOWNA window state, (vol. 1) 4-432 
SW_SHOWNOACTIVATE window state, (vol. 1) 4-432 
SW_SHOWNORMAL window state, (vol. 1) 4-432 
SwapMouseButton function, (vol. 1) 1-30, 4-437 
SwapRecording function, (vol. 1) 3-15, 4-438 
SwitchStackBack function, (vol. 1) 3-5, 4-438 
SwitchStackTo function, (vol. 1) 3-5, 4-438 
SWP_DRAWFRAME window-position flag, (vol. 1) 
4-80, 4-418 
SWP_HIDEWINDOW window-position flag, (vol. 1) 
4-80, 4-418 
SWP_NOACTIVATE window-position flag, (vol. 1) 
4-80, 4-418 
SWP_NOMOVE window-position flag, (vol. 1) 4-80, 
4-418 
SWP_NOREDRAW window-position flag, (vol. 1) 4-80, 
4-418 
SWP_NOSIZE window-position flag, (vol. 1) 4-80, 4-418 
SWP_NOZORDER window-position flag, (vol. 1) 4-80, 
4-418 
SWP_SHOWWINDOW window-position flag, (vol. 1) 
4-80, 4-418 
Symbol redefinition, Cmacro, (vol. 2) 13-10 
SyncAllVoices function, (vol. 1) 3-12, 4-439 
System accelerator (MDI), (vol. 1) 4-445 
SYSTEM_FIXED_FONT stock object, (vol. 1) 4-208 
SYSTEM_FONT stock object, (vol. 1) 4-207 
System functions, (vol. 1) 1-58 
System-menu box, (vol. 1) 1-25, (vol. 2) 8-17 
System palette, retrieving entries, (vol. 1) 4-213 
System services interface, defined, (vol. 1) xix 
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TA_BASELINE text-alignment flag, (vol. 1) 4-218, 4-404 


TA_BOTTOM text-alignment flag, (vol. 1) 4-218, 4-404 
TA_CENTER text-alignment flag, (vol. 1) 4-218, 4-404 
TA_LEFT text-alignment flag, (vol. 1) 4-218, 4-404 
TA_NOUPDATECP text-alignment flag, (vol. 1) 4-218, 
4-404 ; 
TA_RIGHT text-alignment flag, (vol. 1) 4-218, 4-404 
TA_TOP text-alignment flag, (vol. 1) 4-218, 4-404 
TA_UPDATECP text-alignment flag, (vol. 1) 4-218, 
4-404 
Tab stop, (vol. 2) 8-36 
TabbedTextOut function, (vol. 1) 2-28, 4-440 
Table, handle, (vol. 2) 7-38 
Task 

handle, obtaining, (vol. 1) 4-164 

yielding control, (vol. 1) 1-3, 4-469 
Task windows 

enumerating, (vol. 1) 4-123 

posting messages to, (vol. 1) 4-335 
TECHNOLOGY device capability, (vol. 1) 4-167 
Template, DIALOG, (vol. 2) 8-13 
Text 

color, default, (vol. 1) 1-33 

drawing, (vol. 1) 1-42 

graying, (vol. 1) 1-41 
Text control 

left-justified, (vol. 2) 8-20 

right-justified, (vol. 2) 8-21 
Text functions, (vol. 1) 2-27 
TEXTCAPS device capability, (vol. 1) 4-169 
TEXTMETRIC data structure, (vol. 2) 7-59 to 7-61 
TextOut function, (vol. 1) 2-28, 4-441 
Throw function, (vol. 1) 3-7, 4-441 
Timer, killing, (vol. 1) 4-270 
Title bar, (vol. 1) 1-25, (vol. 2) 8-16 to 8-17 
ToAscii function, (vol. 1) 3-9, 4-442 
TrackPopupMenu function, (vol. 1) 1-26, 1-57, 4-59, 
4-443 
TRANSFORM_CTM printer escape, (vol. 2) 12-58 
TranslateAccelerator function, (vol. 1) 1-2, 1-4, 4-444, 
(vol. 2) 8-7 
TranslateMDISysAccel function, (vol. 1) 1-2, 4-445 
TranslateMessage function, (vol. 1) 1-2, 1-4, 4-446 
TransmitCommChar function, (vol. 1) 3-11, 4-446 to 
4-447 
TRANSPARENT background mode, (vol. 1) 4-365 
TWOSTOPBITS stop-bits type, (vol. 2) 7-24 
Types, data, (vol. 2) 7-1 to 7-5 


U 


#undef directive, resource compiler, (vol. 2) 8-48 
UngetCommChar function, (vol. 1) 3-11, 4-448 
Unhook WindowsHook function, (vol. 1) 1-64, 4-448 
UnionRect function, (vol. 1) 1-67, 1-69, 4-449 
UnlockData function, (vol. 1) 3-5, 4-449 
UnlockResource function, (vol. 1) 3-8, 4-450 
UnLockSegment function, (vol. 1) 3-5 to 3-6, 4-450 
UnrealizeObject function, (vol. 1) 2-6, 4-451 
UnregisterClass function, (vol. 1) 1-8, 4-452 
UpdateColors function, (vol. 1) 2-10, 4-452 

Update Window function, (vol. 1) 1-32, 4-453 
Updating region, client area, (vol. 1) 1-38 
User-defined control window, (vol. 2) 8-34 
User-defined resource, (vol. 2) 8-3 

User-defined resource statement, (vol. 2) 8-3 to 8-4 
User-defined variable, (vol. 2) 13-8, 14-7 


V 


ValidateCodeSegments function, (vol. 1) 3-14, 4-454 
ValidateFreeSpaces function, (vol. 1) 3-14, 4-454 
ValidateRect function, (vol. 1) 1-32, 4-455 
ValidateRgn function, (vol. 1) 1-32, 4-455 
Variable 

environmental, INCLUDE, (vol. 2) 8-47 

external, (vol. 2) 14-11 

frame, (vol. 2) 14-12 

global, (vol. 2) 14-11 

local, (vol. 2) 13-8 

names defined, (vol. 2) 14-7 

public, (vol. 2) 14-11 

size, (vol. 2) 14-12 

user-defined, (vol. 2) 13-8, 14-7 
Variable-pitch font attribute, (vol. 1) 2-35 
Vertical bar (I), as document convention, (vol. 1) xxv 
VERTRES device capability, (vol. 1) 4-167 
VERTSIZE device capability, (vol. 1) 4-167 
Viewport 

extents, default, (vol. 1) 1-33 

origin, default, (vol. 1) 1-33 
Virtual-key character, (vol. 2) 8-7 
Virtual-key codes, (vol. 2) A-1 to A-5 
Virtual keys, (vol. 1) 1-4 
VkKeyScan function, (vol. 1) 1-31, 4-456 
void data type, (vol. 2) 7-5 


Ww 


WaitMessage function, (vol. 1) 1-2, 4-457 
WaitSoundState function, (vol. 1) 3-12, 4-457 
WH_CALLWNDPROC windows-hook type, (vol. 1) 
4-419, 4-448 


WH_GETMESSAGE windows-hook type, (vol. 1) 
4-419, 4-448 


WH_JOURNALPLAYBACK windows-hook type, (vol. 


1) 4-419, 4-448 


WH_JOURNALRECORD windows-hook type, (vol. 1) 


4-419, 4-448 


WH_KEYBOARD windows-hook type, (vol. 1) 1-64, 


4-419, 4-448 


WH_MSGFILTER windows-hook type, (vol. 1) 1-64, 


4-419, 4-449 


WH_SYSMSGFILTER windows-hook type, (vol. 1) 


4-419 

WHITE_BRUSH stock object, (vol. 1) 4-207 
WHITE_PEN stock object, (vol. 1) 4-207 
WHITENESS raster-operation code, (vol. 1) 4-19 
WHITEONBLACK stretching mode, (vol. 1) 4-399 
?WIN option, Cmacro, (vol. 2) 13-4 

WINDING filling mode, (vol. 1) 4-58, 4-389 


WINDING polygon-filling mode, (vol. 1) 4-58, 4-197, 


4-389 
Window 
background, (vol. 1) 1-38 
background brush, (vol. 1) 1-11 
border, (vol. 2) 8-16 
brush alignment, (vol. 1) 1-39 
child, (vol. 2) 8-16 
close box, (vol. 1) 1-25 
described, (vol. 1) 1-23 
ID, (vol. 1) 1-23 
input, (vol. 1) 1-23 
messages, (vol. 1) 1-23 
overlapping, (vol. 1) 1-24 
owner window, (vol. 1) 1-23 
showing, (vol. 1) 1-23 
class 
attributes, (vol. 1) 1-10 
background brush, (vol. 1) 1-11, 1-13 
cursor, icon, attributes, (vol. 1) 1-10 
described, (vol. 1) 1-8 © 
functions, (vol. 1) 1-10 
instance handle, (vol. 1) 1-10 
menu, (vol. 1) 1-11, 1-14 
name, (vol. 1) 1-10 
unregistering, (vol. 1) 4-452 
control, user-defined, (vol. 2) 8-34 
creating, (vol. 1) 4-76, (vol. 2) 7-21, 8-15 
dialog box, (vol. 1) 1-43 
disabled, (vol. 2) 8-14, 8-16 
extents, default, (vol. 1) 1-34 
function. See Window function 
icon, (vol. 1) 1-22 
iconic, (vol. 2) 8-17 
main, creating, (vol. 1) 1-27 


MDI, (vol. 1) 1-25 
open, (vol. 1) 1-22 
origin, default, (vol. 1) 1-34 
overlapped, (vol. 1) 1-22 © 
overlapping, (vol. 1) 1-22, (vol. 2) 8-17 
owner, describing, (vol. 1) 1-23 
painting rectangles, (vol. 1) 1-39 
pop-up 
creating and showing, (vol. 1) 1-23 
style, (vol. 2) 8-17 
scroll bars, (vol. 1) 1-25 
size, (vol. 2) 8-17 
state, (vol. 1) 1-27 
style, dialog box, (vol. 2) 8-15 
styles 
child, (vol. 1) 1-22 to 1-23 
described, (vol. 1) 1-21 
listing, (vol. 2) 8-15 
owned, (vol. 1) 1-22 
pop-up, (vol. 1) 1-23 
State, (vol. 1) 1-27 
WS_CHILD, (vol. 2) 8-14 
subclassing, (vol. 1) 1-16, 4-368, 4-416 
System menu box, (vol. 1) 1-25 
title bar, (vol. 1) 1-25 
visible, (vol. 2) 8-18 
window-function address, (vol. 1) 1-12 
zoom, (vol. 2) 8-17 
Window applications 
application queue, (vol. 1) 1-3 
dispatching messages, (vol. 1) 1-3 
pulling messages, (vol. 1) 1-3 
pushing messages, (vol. 1) 1-3 
reading messages, (vol. 1) 1-3 
yielding control, (vol. 1) 1-3 
Window bar menu, (vol. 1) 1-25 
Window function 
address, (vol. 1) 1-12 
receiving messages, (vol. 1) 1-3 
role, (vol. 1) 1-6 
Window manager interface, defined, (vol. 1) xvi 
WindowFromPoint function, (vol. 1) 1-58, 2-20, 4-458 
Windows 
classes, locating, (vol. 1) 1-9 
displaying functions, (vol. 1) 1-28 
enumerating for a task, (vol. 1) 4-123 
epilog, (vol. 2) 13-4 
library, (vol. 2) 13-5 
painting 
drawing, (vol. 1) 1-39 
filling, (vol. 1) 1-39 
inverting, (vol. 1) 1-39 
posting messages to a task, (vol. 1) 4-335 
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prolog, (vol. 2) 13-4 

subclassing, (vol. 1) 1-16 
Windows debugging messages, (vol. 2) C-1 to C-11 
Windows prolog/epilog, Cmacro, (vol. 2) 13-4 
WINDOWS.H initialization file, (vol. 2) 8-15 
WinExec function, (vol. 1) 3-15, 4-458 to 4-459 
WinHelp function, (vol. 1) 3-15, 4-460 to 4-461 
WinMain function 

in assembly-language application, (vol. 2) 13-5 | 

main loop, (vol. 1) 1-4 
WINMEM32.DLL library, (vol. 2) E-1, E-3, E-9 
WM_ACTIVATE message, (vol. 1) 5-2, 6-47 
WM_ACTIVATEAPP message, (vol. 1) 5-2, 6-47 
WM_ASKCBFORMATNAME message, (vol. 1) 5-7, 
6-48 
WM_CANCELMODE message, (vol. 1) 5-2, 6-48 
WM_CHANGECBCHAIN message, (vol. 1) 5-7, 6-49 
WM_CHAR message, (vol. 1) 5-5, 6-49 
WM_CHARTOITEM message, (vol. 1) 5-5, 6-50 
WM_CHILDACTIVATE message, (vol. 1) 5-2, 6-51 
WM_CLEAR message, (vol. 1) 5-11, 6-51 
WM_CLOSE message, (vol. 1) 1-28, 5-2, 6-51 
WM_COMMAND message, (vol. 1) 5-5, 6-52, (vol. 2) ° 
7-17, 8-7 
WM_COMMAND notification codes. See Notification 
codes 
WM_COMPACTING message, (vol. 1) 5-8, 6-52 
WM_COMPAREITEM message, (vol. 1) 5-15, 6-53, 
(vol. 2) 7-19 
WM_COPY, (vol. 1) 5-11, 6-54 
WM_CREATE message, (vol. 1) 4-76, 5-2, 6-54 
WM_CTLCOLOR message, (vol. 1) 5-2, 6-54 
WM_CUT message, (vol. 1) 5-11, 6-55 
WM_DDE_ACK message, (vol. 2) 15-6 to 15-7 
WM_DDE_ADVISE message, (vol. 2) 15-8 to 15-9 
WM_DDE_DATA message, (vol. 2) 15-10 to 15-11 
WM_DDE_EXECUTE message, (vol. 2) 15-12 
WM_DDE_INITIATE message, (vol. 2) 15-13 
WM_DDE_POKE message, (vol. 2) 15-14 to 15-15 
WM_DDE_REQUEST message, (vol. 2) 15-16 
WM_DDE_TERMINATE message, (vol. 2) 15-17 
WM_DDE_UNADVISE message, (vol. 2) 15-17 to 15-18 
WM_DEADCHAR message, (vol. 1) 5-5, 6-55 to 6-56 
WM_DELETEITEM message, (vol. 1) 5-15, 6-8, 6-13, 
6-34, 6-40, 6-57, (vol. 2) 7-26 
WM_DESTROY message, (vol. 1) 1-28, 5-2, 6-57 
WM_DESTROYCLIPBOARD message, (vol. 1) 5-7, 
6-57 
WM_DEVMODECHANGE message, (vol. 1) 5-8, 6-58 
WM_DRAWCLIPBOARD message, (vol. 1) 5-7, 6-58 
WM_DRAWITEM message, (vol. 1) 5-15, 6-58, (vol. 2) 
7-36 
WM_ENABLE message, (vol. 1) 5-2, 6-59 


WM_ENDSESSION message, (vol. 1) 5-2, 6-59 
WM_ENTERIDLE message, (vol. 1) 5-2, 6-60, (vol. 2) 
7-33 

WM_ERASEBKGND message, (vol. 1) 5-2, 6-60 
WM_FONTCHANGE message, (vol. 1) 5-8, 6-61 
WM_GETDLGCODE message, (vol. 1) 5-2, 6-61 
WM_GETFONT message, (vol. 1) 5-9, 6-62 
WM_GETMINMAXINFO message, (vol. 1) 5-3, 6-63 
WM_GETTEXT message, (vol. 1) 5-3, 6-64 
WM_GETTEXTLENGTH message, (vol. 1) 5-3, 6-64 
WM_HSCROLL message, (vol. 1) 1-25, 5-5, 5-17, 6-65 
WM_HSCROLLCLIPBOARD message, (vol. 1) 5-7, 
6-66 

WM_ICONERASEBKGND message, (vol. 1) 5-3, 6-66 
WM_INITDIALOG message, (vol. 1) 4-43 to 4-44, 4-98 
to 4-99, 5-4, 6-67, 6-80 

WM_INITMENU message, (vol. 1) 5-4, 6-67 
WM_INITMENUPOPUP message, (vol. 1) 5-4, 6-68 
WM_KEYDOWN message, (vol. 1) 5-5, 6-68 to 6-69 
WM_KEYUP message, (vol. 1) 5-5, 6-70 
WM_KILLFOCUS message, (vol. 1) 5-3, 6-71 
WM_LBUTTONDBLCLK message, (vol. 1) 5-5, 6-71 
WM_LBUTTONDOWN message, (vol. 1) 5-5, 6-72 
WM_LBUTTONUP message, (vol. 1) 5-5, 6-72 
WM_MBUTTONDBLCLK message, (vol. 1) 5-5, 6-73 
WM_MBUTTONDOWN message, (vol. 1) 5-5, 6-74 
WM_MBUTTONUP message, (vol. 1) 5-5, 6-74 
WM_MDIACTIVATE message, (vol. 1) 5-19, 6-75 
WM_MDICASCADE message, (vol. 1) 5-19, 6-75 
WM_MDICREATE message, (vol. 1) 5-19, 6-75 
WM_MDIDESTROY message, (vol. 1) 5-19, 6-76 
WM_MDIGETACTIVE message, (vol. 1) 5-19, 6-77 
WM_MDIICONARRANGE message, (vol. 1) 5-20, 6-77 
WM_MDIMAXIMIZE message, (vol. 1) 5-20, 6-77 to 
6-78 

WM_MDINEXT message, (vol. 1) 5-20, 6-78 
WM_MDIRESTORE message, (vol. 1) 5-20, 6-78 
WM_MDISETMENU message, (vol. |) 5-20, 6-79 
WM_MDITILE message, (vol. 1) 5-20, 6-79 
WM_MEASUREITEM message, (vol. 1) 5-15, 6-79, 
(vol. 2) 7-48 

WM_MENUCHAR message, (vol. 1) 5-3, 6-80 
WM_MENUSELECT message, (vol. 1) 5-3, 6-81 
WM_MOUSEACTIVATE message, (vol. 1) 5-5, 6-82 
WM_MOUSEMOVE message, (vol. 1) 5-5, 6-82 
WM_MOVE message, (vol. 1) 5-3, 6-83 
WM_NCACTIVATE message, (vol. 1) 5-18, 6-75, 6-83 
WM_NCCALCSIZE message, (vol. 1) 5-18, 6-83 
WM_NCCREATE message, (vol. 1) 5-18, 6-84 
WM_NCDESTROY message, (vol. 1) 5-18, 6-84 
WM_NCHITTEST message, (vol. 1) 5-18, 6-85 
WM_NCLBUTTONDBLCLK message, (vol. 1) 5-18, 
6-86 
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WM_NCLBUTTONDOWN message, (vol. 1) 5-18, 6-86 
WM_NCLBUTTONUP message, (vol. 1) 5-18, 6-87 
WM_NCMBUTTONDBLCLK message, (vol. 1) 5-18, 
6-87 

WM_NCMBUTTONDOWN message, (vol. 1) 5-18, 6-88 
WM_NCMBUTTONUP message, (vol. 1) 5-18, 6-88 
WM_NCMOUSEMOVE message, (vol. 1) 5-19, 6-88 
WM_NCPAINT message, (vol. 1) 5-19, 6-89 
WM_NCRBUTTONDBLCLK message, (vol. 1) 5-19, 
6-89 

WM_NCRBUTTONDOWN message, (vol. 1) 5-19, 6-90 
WM_NCRBUTTONUP message, (vol. 1) 5-19, 6-90 
WM_NEXTDLGCTL message, (vol. 1) 5-9, 6-90 
WM_PAINT message, (vol. 1) 1-37, 5-3, 6-91 
WM_PAINTCLIPBOARD message, (vol. 1) 5-7, 6-91 
WM_PAINTICON message, (vol. 1) 5-3, 6-92 
WM_PALETTECHANGED message, (vol. 1) 5-8, 6-92 
WM_PARENTNOTIFY message, (vol. 1) 5-3, 6-93 
WM_PASTE message, (vol. 1) 5-11, 6-94 
WM_QUERYDRAGICON message, (vol. 1) 5-3, 6-94 
WM_QUERYENDSESSION message, (vol. 1) 5-3, 6-94 
WM_QUERYNEWPALETTE message, (vol. 1) 5-3, 6-95 
WM_QUERYOPEN message, (vol. 1) 5-4, 6-95 
WM_QUIT message, (vol. 1) 1-28, 5-4, 6-96 
WM_RBUTTONDBLCLK message, (vol. 1) 5-6, 6-96 
WM_RBUTTONDOWN message, (vol. 1) 5-6, 6-97 
WM_RBUTTONUP message, (vol. 1) 5-6, 6-97 
WM_RENDERALLFORMATS message, (vol. 1) 5-7, 
6-98 

WM_RENDERFORMAT message, (vol. 1) 5-7, 6-98 
WM_SETCURSOR message, (vol. 1) 5-6, 6-98 
WM_SETFOCUS message, (vol. 1) 5-4, 6-99 
WM_SETFONT message, (vol. 1) 5-4, 5-9, 6-99, (vol. 2) 
7-32 

WM_SETREDRAW message, (vol. 1) 5-4, 6-100 
WM_SETTEXT message, (vol. 1) 5-4, 6-100 
WM_SHOWWINDOW message, (vol. 1) 5-4, 6-101 
WM_SIZE message, (vol. 1) 5-4, 6-102 
WM_SIZECLIPBOARD message, (vol. 1) 5-7, 6-102 
WM_SPOOLERSTATUS message, (vol. 1) 5-8, 6-103 
WM_SYSCHAR message, (vol. 1) 5-6, 6-103 to 6-104 
WM_SYSCOLORCHANGE message, (vol. 1) 5-8, 6-105 
WM_SYSCOMMAND message, (vol. 1) 5-6, 6-105 to 
6-106, (vol. 2) 8-7 

WM_SYSDEADCHAR message, (vol. 1) 5-6, 6-107 
WM_SYSKEYDOWN message, (vol. 1) 5-6, 6-107 
WM_SYSKEYUP message, (vol. 1) 5-7, 6-108 to 6-109 
WM_SYSMENU window style, (vol. 2) 7-32 
WM_TIMECHANGE message, (vol. 1) 5-8, 6-110 
WM_TIMER message, (vol. 1) 5-6, 6-110 

WM_UNDO message, (vol. 1) 5-11, 6-111 

WM_USER message, (vol. 1) 6-1 


WM_VKEYTOITEM message, (vol. 1) 5-6, 6-111 
WM_VSCROLL message, (vol. 1) 1-25, 5-6, 5-17, 6-112 
WM_VSCROLLCLIPBOARD message, (vol. 1) 5-7, 
6-113 

WM_WININICHANGE message, (vol. 1) 5-8, 6-114 
WNDCLASS data structure, (vol. 1) 4-153, (vol. 2) 7-62 
to 7-67 ° 

WORD alignment type, (vol. 2) 14-5 

WORD data type, (vol. 2) 7-5 

Wordwrap, (vol. 2) 8-40 

WriteComm function, (vol. 1) 3-11, 4-462 
WritePrivateProfileString function, (vol. 1) 3-10, 4-462 
to 4-463 

WriteProfileString function, (vol. 1) 3-10, 4-464 
WS_BORDER window style, (vol. 1) 4-66, (vol. 2) 8-16, 
8-26, 8-32 

WS_CAPTION window style, (vol. 1) 1-25, 1-45, 4-66, 
6-76, (vol. 2) 7-32, 8-16 

WS_CHILD window style, (vol. 1) 1-23, 4-66, 6-76, 
(vol. 2) 8-14, 8-16 

WS_CHILDWINDOW window style, (vol. 1) 4-66, (vol. 
2) 8-16 

WS_CLIPCHILDREN window style, (vol. 1) 4-66, 6-76, 
(vol. 2) 8-16 

WS_CLIPSIBLINGS window style, (vol. 1) 4-66, 6-76, 
(vol. 2) 8-16 

WS_DISABLED window style, (vol. 1) 4-67, (vol. 2) 
8-16, 8-25, 8-27, 8-29 to 8-31 

WS_DLGFRAME window style, (vol. 1) 4-67, (vol. 2) 
8-16 

WS_EX_DLGMODALFRAME extended window style, 
(vol. 1) 4-77 

WS_EX_NOPARENTNOTIFY extended window style, 
(vol. 1) 4-77 

WS_GROUP window style, (vol. 1) 4-67, (vol. 2) 8-17, 
8-21 to 8-25, 8-29 to 8-31 

WS_HSCROLL window style, (vol. 1) 4-67, (vol. 2) 
7-48, 8-17, 8-31 

WS_ICONIC window style, (vol. 1) 4-67, (vol. 2) 8-17 
WS_MAXIMIZE window style, (vol. 1) 4-67, (vol. 2) 
7-48, 8-17 

WS_MAXIMIZEBOX window style, (vol. 1) 4-67, 6-76, 
(vol. 2) 8-17 
WS_MINIMIZE window style, (vol. 1) 4-67, (vol. 2) 
7-48, 8-17 

WS_MINIMIZEBOX window style, (vol. 1) 4-67, (vol. 
2) 8-17 

WS_OVERLAPPED window style, (vol. 1) 1-22, 4-67, 
(vol. 2) 8-17 

WS_OVERLAPPEDWINDOW window style, (vol. 1) 
1-22, 4-67, (vol. 2) 8-17 

WS_POPUP window style, (vol. 1) 1-23, 4-67, (vol. 2) 
8-17 
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WS_POPUPWINDOW window style, (vol. 1) 4-67, (vol. 
2) 8-17 

WS_SIZEBOX window style, (vol. 2) 8-17 
WS_SYSMENU window style, (vol. 1) 1-25, 1-45, 4-66 
to 4-67, 6-76, (vol. 2) 8-16 to 8-17 

WS_TABSTOP window style, (vol. 1) 4-67, (vol. 2) 
8-17, 8-21 to 8-25, 8-27, 8-29 to 8-31 , 
WS_THICKFRAME window style, (vol. 1) 4-68, 6-76, 
(vol. 2) 8-18 

WS_VISIBLE window style, (vol. 1) 4-68, (vol. 2) 8-18 
WS_VSCROLL window style, (vol. 1) 4-68, (vol. 2) 
7-48, 8-18, 8-26, 8-31 to 8-32 

wsprintf function, (vol. 1) 3-9, 4-465 to 4-466 

wysprintf function, (vol. 1) 3-9, 4-467 to 4-468 
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Yield function, (vol. 1) 3-7, 4-469 to 4-470 
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